Skip to content

Commit 9feb708

Browse files
kelly-sovacoolkelly-sovacool
committed
ci: add gha workflows from MOSuite
1 parent 14f150b commit 9feb708

8 files changed

Lines changed: 538 additions & 0 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
# Contributing to SCWorkflow
2+
3+
## Proposing changes with issues
4+
5+
If you want to make a change, it's a good idea to first
6+
[open an issue](https://code-review.tidyverse.org/issues/)
7+
and make sure someone from the team agrees that it’s needed.
8+
9+
If you've decided to work on an issue,
10+
[assign yourself to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users#assigning-an-individual-issue-or-pull-request)
11+
so others will know you're working on it.
12+
13+
## Pull request process
14+
15+
We use [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
16+
as our collaboration process.
17+
Follow the steps below for detailed instructions on contributing changes to
18+
SCWorkflow.
19+
20+
![GitHub Flow diagram](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/GitHub-Flow_bg-white.png)
21+
22+
23+
### Clone the repo
24+
25+
If you are a member of [CCBR](https://github.com/CCBR),
26+
you can clone this repository to your computer or development environment.
27+
Otherwise, you will first need to
28+
[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
29+
the repo and clone your fork. You only need to do this step once.
30+
31+
```sh
32+
git clone https://github.com/CCBR/SCWorkflow
33+
```
34+
35+
> Cloning into 'SCWorkflow'... <br>
36+
> remote: Enumerating objects: 1136, done. <br>
37+
> remote: Counting objects: 100% (463/463), done. <br>
38+
> remote: Compressing objects: 100% (357/357), done. <br>
39+
> remote: Total 1136 (delta 149), reused 332 (delta 103), pack-reused 673 <br>
40+
> Receiving objects: 100% (1136/1136), 11.01 MiB | 9.76 MiB/s, done. <br>
41+
> Resolving deltas: 100% (530/530), done. <br>
42+
43+
```sh
44+
cd SCWorkflow
45+
```
46+
47+
### If this is your first time cloning the repo, install dependencies
48+
49+
- In an R console, install the R development dependencies with
50+
`devtools::install_dev_deps()`, and then make sure the package passes R CMD
51+
check by running `devtools::check()`. If R CMD check doesn't pass cleanly,
52+
it's a good idea to ask for help before continuing.
53+
54+
- Install [`pre-commit`](https://pre-commit.com/#install) if you don't already
55+
have it. Then from the repo's root directory, run
56+
57+
```sh
58+
pre-commit install
59+
```
60+
61+
This will install the repo's pre-commit hooks.
62+
You'll only need to do this step the first time you clone the repo.
63+
64+
### Create a branch
65+
66+
Create a Git branch for your pull request (PR). Give the branch a descriptive
67+
name for the changes you will make, such as `iss-10` if it is for a specific
68+
issue.
69+
70+
```sh
71+
# create a new branch and switch to it
72+
git branch iss-10
73+
git switch iss-10
74+
```
75+
76+
> Switched to a new branch 'iss-10'
77+
78+
### Make your changes
79+
80+
Edit the code, write unit tests, and update the documentation as needed.
81+
82+
#### style
83+
84+
New code should follow the [tidyverse style guide](https://style.tidyverse.org).
85+
You can use the [styler](https://CRAN.R-project.org/package=styler) package to
86+
apply these styles, but please don't restyle code that has nothing to do with
87+
your PR.
88+
89+
A brief overview of conventions according to the tidyverse style guide:
90+
91+
- most object names (variables and functions) should be in [snake_case](https://style.tidyverse.org/syntax.html#sec-objectnames)
92+
- function names should use [verbs](https://style.tidyverse.org/functions.html#naming) where possible
93+
- use `<-` for assignment
94+
- use [pipes](https://style.tidyverse.org/pipes.html) to chain operations on a single object
95+
96+
Please see the [tidyverse style guide](https://style.tidyverse.org) for more details.
97+
98+
#### test
99+
100+
Most changes to the code will also need unit tests to demonstrate that the
101+
changes work as intended.
102+
Use [`testthat`](https://testthat.r-lib.org/) to create your unit tests and test
103+
the code.
104+
Test files are organized as described in
105+
<https://style.tidyverse.org/tests.html>.
106+
Take a look at the existing code in this package for examples.
107+
108+
#### document
109+
110+
If you have written a new function or changed the API of an existing function,
111+
you will need to update the function's documentation using
112+
[roxygen2](https://cran.r-project.org/package=roxygen2) with
113+
[Markdown syntax](https://roxygen2.r-lib.org/articles/rd-formatting.html).
114+
See instructions on writing roxygen2 comments here:
115+
<https://r-pkgs.org/man.html>.
116+
If the function is used in a vignette, you may also need to update the vignette.
117+
118+
#### check
119+
120+
After making your changes, run `devtools::check()` from an R console to make
121+
sure the package still passes R CMD check.
122+
123+
### Commit and push your changes
124+
125+
If you're not sure how often you should commit or what your commits should
126+
consist of, we recommend following the "atomic commits" principle where each
127+
commit contains one new feature, fix, or task.
128+
Learn more about atomic commits here:
129+
<https://www.freshconsulting.com/insights/blog/atomic-commits/>
130+
131+
First, add the files that you changed to the staging area:
132+
133+
```sh
134+
git add path/to/changed/files/
135+
```
136+
137+
Then make the commit.
138+
Your commit message should follow the
139+
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
140+
specification.
141+
Briefly, each commit should start with one of the approved types such as
142+
`feat`, `fix`, `docs`, etc. followed by a description of the commit.
143+
Take a look at the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary)
144+
for more detailed information about how to write commit messages.
145+
146+
147+
```sh
148+
git commit -m 'feat: create function for awesome feature'
149+
```
150+
151+
pre-commit will enforce that your commit message and the code changes are
152+
styled correctly and will attempt to make corrections if needed.
153+
154+
> Check for added large files..............................................Passed <br>
155+
> Fix End of Files.........................................................Passed <br>
156+
> Trim Trailing Whitespace.................................................Failed <br>
157+
> - hook id: trailing-whitespace <br>
158+
> - exit code: 1 <br>
159+
> - files were modified by this hook <br>
160+
> <br>
161+
> Fixing path/to/changed/files/file.txt <br>
162+
> <br>
163+
> codespell................................................................Passed <br>
164+
> style-files..........................................(no files to check)Skipped <br>
165+
> readme-rmd-rendered..................................(no files to check)Skipped <br>
166+
> use-tidy-description.................................(no files to check)Skipped <br>
167+
168+
In the example above, one of the hooks modified a file in the proposed commit,
169+
so the pre-commit check failed. You can run `git diff` to see the changes that
170+
pre-commit made and `git status` to see which files were modified. To proceed
171+
with the commit, re-add the modified file(s) and re-run the commit command:
172+
173+
```sh
174+
git add path/to/changed/files/file.txt
175+
git commit -m 'feat: create function for awesome feature'
176+
```
177+
178+
This time, all the hooks either passed or were skipped
179+
(e.g. hooks that only run on R code will not run if no R files were
180+
committed).
181+
When the pre-commit check is successful, the usual commit success message
182+
will appear after the pre-commit messages showing that the commit was created.
183+
184+
> Check for added large files..............................................Passed <br>
185+
> Fix End of Files.........................................................Passed <br>
186+
> Trim Trailing Whitespace.................................................Passed <br>
187+
> codespell................................................................Passed <br>
188+
> style-files..........................................(no files to check)Skipped <br>
189+
> readme-rmd-rendered..................................(no files to check)Skipped <br>
190+
> use-tidy-description.................................(no files to check)Skipped <br>
191+
> Conventional Commit......................................................Passed <br>
192+
> [iss-10 9ff256e] feat: create function for awesome feature <br>
193+
> 1 file changed, 22 insertions(+), 3 deletions(-) <br>
194+
195+
Finally, push your changes to GitHub:
196+
197+
```sh
198+
git push
199+
```
200+
201+
If this is the first time you are pushing this branch, you may have to
202+
explicitly set the upstream branch:
203+
204+
```sh
205+
git push --set-upstream origin iss-10
206+
```
207+
208+
> Enumerating objects: 7, done. <br>
209+
> Counting objects: 100% (7/7), done. <br>
210+
> Delta compression using up to 10 threads <br>
211+
> Compressing objects: 100% (4/4), done. <br>
212+
> Writing objects: 100% (4/4), 648 bytes | 648.00 KiB/s, done. <br>
213+
> Total 4 (delta 3), reused 0 (delta 0), pack-reused 0 <br>
214+
> remote: Resolving deltas: 100% (3/3), completed with 3 local objects. <br>
215+
> remote: <br>
216+
> remote: Create a pull request for 'iss-10' on GitHub by visiting: <br>
217+
> remote: https://github.com/CCBR/SCWorkflow/pull/new/iss-10 <br>
218+
> remote: <br>
219+
> To https://github.com/CCBR/SCWorkflow <br>
220+
> <br>
221+
> [new branch] iss-10 -> iss-10 <br>
222+
> branch 'iss-10' set up to track 'origin/iss-10'. <br>
223+
224+
We recommend pushing your commits often so they will be backed up on GitHub.
225+
You can view the files in your branch on GitHub at
226+
`https://github.com/CCBR/SCWorkflow/tree/<your-branch-name>`
227+
(replace `<your-branch-name>` with the actual name of your branch).
228+
229+
### Create the PR
230+
231+
Once your branch is ready, create a PR on GitHub:
232+
<https://github.com/CCBR/SCWorkflow/pull/new/>
233+
234+
Select the branch you just pushed:
235+
236+
![Create a new PR from your branch](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/new-PR.png)
237+
238+
Edit the PR title and description.
239+
The title should briefly describe the change.
240+
Follow the comments in the template to fill out the body of the PR, and
241+
you can delete the comments (everything between `<!--` and `-->`) as you go.
242+
When you're ready, click 'Create pull request' to open it.
243+
244+
![Open the PR after editing the title and description](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/create-PR.png)
245+
246+
Optionally, you can mark the PR as a draft if you're not yet ready for it to
247+
be reviewed, then change it later when you're ready.
248+
249+
### Wait for a maintainer to review your PR
250+
251+
We will do our best to follow the tidyverse code review principles:
252+
<https://code-review.tidyverse.org/>.
253+
The reviewer may suggest that you make changes before accepting your PR in
254+
order to improve the code quality or style.
255+
If that's the case, continue to make changes in your branch and push them to
256+
GitHub, and they will appear in the PR.
257+
258+
Once the PR is approved, the maintainer will merge it and the issue(s) the PR
259+
links will close automatically.
260+
Congratulations and thank you for your contribution!
261+
262+
### After your PR has been merged
263+
264+
After your PR has been merged, update your local clone of the repo by
265+
switching to the main branch and pulling the latest changes:
266+
267+
```sh
268+
git checkout main
269+
git pull
270+
```
271+
272+
It's a good idea to run `git pull` before creating a new branch so it will
273+
start from the most recent commits in main.
274+
275+
## Helpful links for more information
276+
277+
- This contributing guide was adapted from the [tidyverse contributing guide](https://github.com/tidyverse/tidyverse/blob/main/.github/CONTRIBUTING.md)
278+
- [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
279+
- [tidyverse style guide](https://style.tidyverse.org)
280+
- [tidyverse code review principles](https://code-review.tidyverse.org)
281+
- [reproducible examples](https://www.tidyverse.org/help/#reprex)
282+
- [R packages book](https://r-pkgs.org/)
283+
- packages:
284+
- [usethis](https://usethis.r-lib.org/)
285+
- [devtools](https://devtools.r-lib.org/)
286+
- [testthat](https://testthat.r-lib.org/)
287+
- [styler](https://styler.r-lib.org/)
288+
- [roxygen2](https://roxygen2.r-lib.org)

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Bug report
2+
description: Report something that is broken or incorrect
3+
labels: bug
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Before you submit this issue, please check the documentation: <https://ccbr.github.io/SCWorkflow/>
9+
10+
- type: textarea
11+
id: description
12+
attributes:
13+
label: Description of the bug
14+
description: A clear and concise description of what the bug is.
15+
validations:
16+
required: true
17+
18+
- type: textarea
19+
id: reprex
20+
attributes:
21+
label: Code and output
22+
description: Please include a minimal reproducible example (AKA a reprex). If you've never heard of a [reprex](http://reprex.tidyverse.org/) before, start by reading <https://www.tidyverse.org/help/#reprex>.
23+
render: console
24+
placeholder: |
25+
library(SCWorkflow)
26+
... insert_your_code_here() ...
27+
28+
Paste some output where something broke
29+
30+
- type: textarea
31+
id: files
32+
attributes:
33+
label: Relevant files
34+
description: |
35+
Please drag and drop any relevant files here if applicable. Create a `.zip` archive if the extension is not allowed.
36+
37+
- type: textarea
38+
id: system
39+
attributes:
40+
label: System information
41+
description: |
42+
* Version of R
43+
* Version of CCBR/SCWorkflow
44+
* OS _(eg. Ubuntu Linux, macOS)_
45+
* Hardware _(eg. HPC, Desktop)_

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
contact_links:
2+
- name: Discussions
3+
url: https://github.com/CCBR/SCWorkflow/discussions
4+
about: Please ask and answer questions here.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: Feature request
2+
description: Suggest an idea for the package
3+
labels: enhancement
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: Description of feature
9+
description: Please describe your suggestion for a new feature. It might help to describe a problem or use case, plus any alternatives that you have considered.
10+
validations:
11+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Changes
2+
3+
<!--
4+
Provide a brief summary of what is included in this Pull Request (PR).
5+
-->
6+
7+
## Issues
8+
9+
<!--
10+
Reference any issues related to this PR.
11+
If this PR fixes any issues,
12+
[use a keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
13+
when referring to the issue so it will be closed automatically when the PR is merged.
14+
-->
15+
16+
## PR Checklist
17+
18+
(~Strikethrough~ any points that are not applicable.)
19+
20+
- [ ] This comment contains a description of changes with justifications, with any relevant issues linked.
21+
- [ ] Write unit tests for any new features, bug fixes, or other code changes.
22+
- [ ] Update the docs if there are any API changes (roxygen2 comments, vignettes, readme, etc.).
23+
- [ ] Update `NEWS.md` with a short description of any user-facing changes and reference the PR number. Follow the style described in <https://style.tidyverse.org/news.html>
24+
- [ ] Run `devtools::check()` locally and fix all notes, warnings, and errors.

0 commit comments

Comments
 (0)