This page is now obsolete. It is superseded by OEP-55: Project Maintainers.
(This is a proposal, comments welcome.)
If a GitHub repository is public, it must have:
A license, either AGPL or Apache. Here’s how to choose: https://openedx.atlassian.net/wiki/spaces/OPEN/pages/13959332
An openedx.yaml file. See OEP-2: Repository Metadata for details.
A README file (README.rst) with:
A sentence (ideally more) describing what the repo is. A brief summary of what it is for, and who might be interested is useful. More details can be covered in ADRs (described in OEP-19: Developer Documentation).
A link to the code of conduct: https://open.edx.org/code-of-conduct/
A mention of the license.
A statement about the repo’s contribution stance. For example:
“We welcome contributions”, with a link to a Contributing document [TODO: update a good org-wide contribution document.]
“We are not accepting public contributions to this repo.”
Contact information. This can simply be oscm@edx.org.
Security reporting information: “Please do not report security issues in public. Send security concerns via email to security@edx.org.”
A public repo should have:
A changelog
A link to documentation. There’s a variety of docs that could be available, described in OEP-19: Developer Documentation.
Information about how to report issues.
Where to go for help with the repo.
A public repo accepting contributions should have:
A pull request template
Comments
I didn’t think any of the “musts” were difficult. How would you change them?
@Ned Batchelder (Deactivated) They aren’t difficult, and are perfectly reasonable. It’s more that between no code published at all, and having the requirements fulfilled, I would still take the publication for the “raw” code without explanations. Maybe that could be a type of status, similar to “We welcome contributions” vs “We don’t” - ie an option to simply say “We haven’t properly formatted this repo description yet, but here is the code already”? Often it’s the initial psychological step to publish the code that stops people.
It’s not too important - it’s more a remark that came to mind in passing, but I thought I would mention it.
Note that we have cookiecutter templates for new repos which do most of this automatically, so it’s actually pretty easy to comply with: https://github.com/edx/edx-cookiecutters
Possible TODOs:
Extract the README section and make a child page that explains some of the integrations running off the README (e.g. link to backstage docs) and link to template / example README (afaik right now that is just the DoneXBlock README)
Take steps to remove the proposal disclaimer and make this Facts
Link to resources like https://github.com/edx/edx-cookiecutters which are relevant to the various requirements
@Ned Batchelder (Deactivated) Thanks for putting this together!
Reading this prompted a question for me - is the default with Open edX repos to be public still, or did I correctly hear that now keeping repos private is more of an option than it was in the past? If the later, wouldn’t adding strong requirements for public repos push people to keep them private?