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:

With the usethis package you can add an entry of type person to the DESCRIPTION file of your package

usethis::use_author("Fred Hutchinson Cancer Center", role = "fnd", email = "wilds@fredhutch.org")

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:

gh label clone getwilds/source-repo-name \
  --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.

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.

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.

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.