search

18F / open-source-policy

This repository contains the official Open Source Policy of 18F
https://18f.gsa.gov
Other
298 stars 94 forks source link

Document why a repo is private #70

Closed mgwalker closed 6 years ago

mgwalker commented 7 years ago

From https://gsa-tts.slack.com/archives/C02KXM98G/p1490369907134478

The idea is to capture why a repo is private and make that accessible from within the repo itself, so folks in the future will understand the rationale. As @stvnrlly pointed out, putting that explanation directly into the README could make it impossible to ever open the repo up since it would forever be part of the history (nasty git history rewrites notwithstanding). Instead, maybe a Google doc and then a link in the README.

In any case, capturing the reasoning in a way that's easy to pull up later would be nice! I'm no wordsmith, so if someone has better wording, let's have it! 😄

Counterpart to 18F/handbook#335

konklone commented 7 years ago

I think this might be better done as part of practice.md, since it's an implementation-level decision. It's also where we list the actual exceptions, so anything that's abiding by this text should be cross-linked back from practice.md.

konklone commented 7 years ago

(And I'm a :+1: on the substance of the change.)

mgwalker commented 7 years ago

Putting this in practice.md makes sense to me. Let me see bang on it a little bit and see what I can come up with.

stvnrlly commented 7 years ago

I'm 👍 on this.

Two additional thoughts for future elaboration:

  1. I wonder if there is a template of what should be in that documentation, as it seems (from my indirect experience) like there are specific things. Or, if not a template, examples.

  2. While a Google doc is a nice way to go, I wonder if we should encourage people to document the decision in the repo where the reasoning can later be made public along with the repo. It could either be in the README or something like a LICENSE file that's summarized and linked to.

mgwalker commented 7 years ago

@stvnrlly Google doc was your idea. 🤣 I'm :100: for putting it in the README if possible, but if the reasoning itself is sensitive for some reason, we don't want to capture that in the repo history because that would make it harder/impossible to make it public in the future (which is what I gathered you were concerned about). However, what you say here is great too.

mgwalker commented 7 years ago

Sorry for taking so long to get back to this. Rolled back the changes in policy.md and put the changes in practice.md instead, per @konklone's suggestion and wiggled the words a little bit.

konklone commented 7 years ago

:+1: from me