12 Conventions
12.1 Mention our employer
In all repositories in WILDS we will include mention of our employer. The following are examples for R and Python:
- R:
- With the
usethis
package you can add an entry of typeperson
to the DESCRIPTION file of your package
::use_author("Fred Hutchinson Cancer Center", role = "fnd", email = "wilds@fredhutch.org") usethis
- With the
- Python:
- Add a dict in the authors block of the pyproject.toml file or other config file in your package
{ name = "Fred Hutchinson Cancer Center"", email = "wilds@fredhutch.org" }
For other types of WILDS repositories, perhaps just add a mention to the README.
12.2 GitHub Repositories
12.2.1 Issue labels
In the WILDS repo sixtyfour
there’s a set of 9 labels that have been proposed as common labels across WILDS repos. These aren’t necessarily enforced across WILDS repos, but can be used.
Though we have not done this, one can set default labels for all repositories in WILDS - instructions here.
A blogpost shows how to copy labels from one repository to another using the gh command line tool from GitHub. This command line method may be a better choice if we’re not sure we want to go all in on default labels for every new repo. Here’s the command:
/source-repo-name \
gh label clone getwilds--repo getwilds/destination-repo-name \
--force
12.2.2 Badges
WILDS projects will use badges to indicate their status. Badges are a widely used standard in source code repositories, and help quickly indicate to a potential user something typically important about the repository.
WILDS badges are maintained in a GitHub repository at https://github.com/getwilds/badges. There’s a website for these badges and an easy click to copy interface at https://getwilds.org/badges/.
Each status has a set of corresponding practices with respect to the following (which you can find throughout this book):
- Versioning
- Branching
- Code Review
- Testing
- Documentation
- Releases
12.2.2.1 Statuses
- Concept
Not useable, no support, not open to feedback, unstable API.
- Experimental
Useable, some support, not open to feedback, unstable API.
- Prototype
Useable, some support, open to feedback, unstable API.
- Stable
Useable, full support, open to feedback, stable API.
- Deprecated
Useable as of a fixed, past date, no support, not open to feedback, stable API as of a fixed, past date.
12.2.3 Contributing instructions
All WILDS repos should have a CONTRIBUTING.md
file. Although this file could live in many different places in a repository, in WILDS repositories it should live in the .github/
directory.
See also GitHub’s docs on CONTRIBUTING.md.
There is a default CONTRIBUTING.md file for all WILDS repos at https://github.com/getwilds/.github. We encourage repo maintainers to add their own CONTRIBUTING.md file if the default is not adequate.
12.2.4 Pull request templates
All WILDS repos should have one or more pull request templates. These help contributors include all the relavant information, and perform any required tasks, before submitting a pull request.
See also GitHub’s docs on pull request templates
There is a default pull request template for all WILDS repos at https://github.com/getwilds/.github. We encourage repo maintainers to add their own pull request template if the default is not adequate.
12.2.5 Issue templates
All WILDS repos should have one or more issue templates. These help contributors include all the relavant information, and perform any required tasks, before submitting an issue.
See also GitHub’s docs on issue templates
There is a default issue template for all WILDS repos at https://github.com/getwilds/.github. We encourage repo maintainers to add their own issue template(s) if the default is not adequate.
12.2.6 Reproducible examples
We strongly encourage all repositories that are R or Python packages or research compendia to request a “reprex” (reproducible example) in their issue and pull request templates.
- R: reprex
- Python: reprexlite, reprexpy
12.2.7 GitHub Actions
(For brevity we’ll use the shorthand “GH actions”)
- R: The
usethis
function use_github_actions can be used to add many different GH actions, e.g.,use_github_action("pkgdown")
. For R packages, we recommend using the following three:use_github_action("check-standard")
use_github_action("lint")
use_github_action("pkgdown")
- Python: There is no tool available for Python similar to
usethis
- one has to manually add workflow files. For Python packages we recommend following GitHub’s guide on Building and Testing Python. As there are many different ways to make and maintain Python packages, you will need to decide what steps are needed for your package.