STScI-owned repositories on GitHub have conventions for the following:
- Naming
- Repository descriptions
- Repository website
- README
- Repository tags/topics
- Maintainers
- License
- Code of conduct
- Contributor guidelines
- Releases
- Status
Pick a logical, ideally human-readable name. Hyphens are preferred over underscores e.g. style-guides not style_guides
Repository descriptions should be short (ideally 20 words or less) but descriptive. See asdf as a good example:
ASDF (Advanced Scientific Data Format) is a next generation interchange format for scientific data
The website field should link to the software documentation or user guides. Basically wherever you think users of the software should go first.
Readme should include short statement of need. What is this software, what does it do? The README should also link out to other resources in the repository such as contributing guidelines, who the maintainers are, the code of conduct etc.
Repository topics are used to index and search our repositories on the stsci.edu website. Mission and instrument abbreviations are preferred to full names e.g. hst not hubble space telescope and cos not cosmic origins spectrograph.
We follow GitHub's CODEOWNERS convention: https://help.github.com/articles/about-codeowners/
# Lines starting with '#' are comments.
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in the repo.
* @arfon
# Order is important. The last matching pattern has the most precedence.
# So if a pull request only touches javascript files, only these owners
# will be requested to review.
*.js @octocat @github/js
# You can also use email addresses if you prefer.
docs/* docs@example.com
BSD 3-Clause is the preferred license for STScI produced open source software. A plain text file named LICENSE should be at the top level of the repository.
The copyright holder should be 'Association of Universities for Research in Astronomy'. Example license
We expect all STScI projects to adopt a code of conduct that ensures a productive, respectful environment for all open source contributors and participants. A file named CODE_OF_CONDUCT.md should be at the top level of the repository and should have the following content: Example code of conduct
When possible, include contributing guidelines in your repository either as a section named Contributing in the README or in a dedicated file named CONTRIBUTING.md
Each repository should have an Issue Template and a PR Template. To include these, copy the templates out of style guide template directory, place into the root of the GitHub repository and call the files ISSUE_TEMPLATE and PULL_REQUEST_TEMPLATE.
More information is found on the GitHub website
Where possible use GitHub releases following SemVer conventions.
Actively maintained or not? If not, mark your repository as archived.