-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathconventions.qmd
145 lines (92 loc) · 6.96 KB
/
conventions.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
# Conventions {{< iconify fa6-solid person-digging >}} {#sec-conventions}
## Mention our employer
{{< var rule-badge >}} {{< var rules.mention-our-employer >}}
The following are examples for R and Python:
### R
Use the `usethis` package to add an entry of type `person` to the DESCRIPTION file of your package
```r
# install.packages("pak")
pak::pak("usethis")
usethis::use_author("Fred Hutchinson Cancer Center", role = "fnd", email = "[email protected]")
```
And use the `desc` package to add a Research Organization (ROR) identifier for Fred Hutch
```r
# `desc` version 1.4.3.9000 or greater for function `desc_add_ror`
pak::pak("r-lib/desc")
desc::desc_add_ror(ror = "007ps6h72", given = "Fred Hutchinson Cancer Center")
```
Which should give you in your `DESCRIPTION` file:
> person("Fred Hutchinson Cancer Center", , , "[email protected]",
role = "fnd", comment = c(ROR = "007ps6h72"))
### Python
Add a dict in the authors block of the pyproject.toml file in your package:
```toml
authors = [
{
name = "Fred Hutchinson Cancer Center",
email = "[email protected]"
}
]
```
Then add the ROR identifier as:
```toml
[tool.package-name.metadata]
authors = [
{
name = "Fred Hutchinson Cancer Center",
ror = "007ps6h72"
}
]
```
For other types of WILDS repositories, perhaps just add a mention to the README.
## GitHub Repositories {#sec-conventions-repos}
### Issue labels
In the WILDS repo `sixtyfour` there's [a set of 9 labels](https://github.com/getwilds/sixtyfour/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](https://docs.github.com/en/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization).
A [blogpost](https://napjose.ph/posts/copy-issue-labels-from-another-github-repository) shows how to copy labels from one repository to another using the [gh command line tool](https://cli.github.com/) 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:
```r
gh label clone getwilds/source-repo-name \
--repo getwilds/destination-repo-name \
--force
```
### Badges
{{< var rule-badge >}} {{< var rules.status-badge >}}
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
<!-- An example badge: [](https://getwilds.org/badges/#stable) -->
#### Statuses
- **Concept** [](https://getwilds.org/badges/#concept) Not useable, no support, not open to feedback, unstable API.
- **Experimental** [](https://getwilds.org/badges/#experimental) Useable, some support, not open to feedback, unstable API.
- **Prototype** [](https://getwilds.org/badges/#prototype) Useable, some support, open to feedback, unstable API.
- **Stable** [](https://getwilds.org/badges/#stable) Useable, full support, open to feedback, stable API.
- **Deprecated** [](https://getwilds.org/badges/#deprecated) Useable as of a fixed, past date, no support, not open to feedback, stable API as of a fixed, past date.
### 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](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors).
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.
### 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](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)
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.
### 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](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository)
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.
### 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](https://www.tidyverse.org/help/#reprex)
- Python: [reprexlite](https://pypi.org/project/reprexlite/), [reprexpy](https://pypi.org/project/reprexpy/)
### GitHub Actions
(For brevity we'll use the shorthand "GH actions")
- R: The `usethis` function [use_github_actions](https://usethis.r-lib.org/reference/use_github_action.html) 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](https://docs.github.com/en/actions/automating-builds-and-tests/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.