diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..80756a4 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,278 @@ +# Contributing to reneeTools + +## Proposing changes with issues + +If you want to make a change, it's a good idea to first +[open an issue](https://code-review.tidyverse.org/issues/) +and make sure someone from the team agrees that it’s needed. + +If you've decided to work on an issue, +[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) +so others will know you're working on it. + +## Pull request process + +We use [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) +as our collaboration process. +Follow the steps below for detailed instructions on contributing changes to +reneeTools. + +![GitHub Flow diagram](./img/GitHub-Flow_bg-white.png) + +### Clone the repo + +If you are a member of [CCBR](https://github.com/CCBR), +you can clone this repository to your computer or development environment. +Otherwise, you will first need to +[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) +the repo and clone your fork. You only need to do this step once. + +```sh +git clone https://github.com/CCBR/reneeTools +``` + +> Cloning into 'reneeTools'...
+> remote: Enumerating objects: 1136, done.
+> remote: Counting objects: 100% (463/463), done.
+> remote: Compressing objects: 100% (357/357), done.
+> remote: Total 1136 (delta 149), reused 332 (delta 103), pack-reused 673
+> Receiving objects: 100% (1136/1136), 11.01 MiB | 9.76 MiB/s, done.
+> Resolving deltas: 100% (530/530), done.
+ +```sh +cd reneeTools +``` + +### If this is your first time cloning the repo, install dependencies + +- In an R console, install the R development dependencies with + `devtools::install_dev_deps()`, and then make sure the package passes R CMD + check by running `devtools::check()`. If R CMD check doesn't pass cleanly, + it's a good idea to ask for help before continuing. + +- Install [`pre-commit`](https://pre-commit.com/#install) if you don't already + have it. Then from the repo's root directory, run + + ```sh + pre-commit install + ``` + + This will install the repo's pre-commit hooks. + You'll only need to do this step the first time you clone the repo. + +### Create a branch + + Create a Git branch for your pull request (PR). Give the branch a descriptive + name for the changes you will make, such as `iss-10` if it is for a specific + issue. + + ```sh + # create a new branch and switch to it + git branch iss-10 + git switch iss-10 + ``` + + > Switched to a new branch 'iss-10' + +### Make your changes + +Edit the code, write unit tests, and update the documentation as needed. + +#### style + +New code should follow the tidyverse [style guide](https://style.tidyverse.org). +You can use the [styler](https://CRAN.R-project.org/package=styler) package to +apply these styles, but please don't restyle code that has nothing to do with +your PR. + +#### test + +Most changes to the code will also need unit tests to demonstrate that the +changes work as intended. +Use [`testthat`](https://testthat.r-lib.org/) to create your unit tests and test +the code. +Test files are organized as described in +. +Take a look at the existing code in this package for examples. + +#### document + +If you have written a new function or changed the API of an existing function, +you will need to update the function's documentation using +[roxygen2](https://cran.r-project.org/package=roxygen2) with +[Markdown syntax](https://roxygen2.r-lib.org/articles/rd-formatting.html). +See instructions on writing roxygen2 comments here: +. +If the function is used in a vignette, you may also need to update the vignette. + +#### check + +After making your changes, run `devtools::check()` from an R console to make +sure the package still passes R CMD check. + +### Commit and push your changes + +If you're not sure how often you should commit or what your commits should +consist of, we recommend following the "atomic commits" principle where each +commit contains one new feature, fix, or task. +Learn more about atomic commits here: + + +First, add the files that you changed to the staging area: + +```sh +git add path/to/changed/files/ +``` + +Then make the commit. +Your commit message should follow the +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +specification. +Briefly, each commit should start with one of the approved types such as +`feat`, `fix`, `docs`, etc. followed by a description of the commit. +Take a look at the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary) +for more detailed information about how to write commit messages. + + +```sh +git commit -m 'feat: create function for awesome feature' +``` + +pre-commit will enforce that your commit message and the code changes are +styled correctly and will attempt to make corrections if needed. + +> Check for added large files..............................................Passed
+> Fix End of Files.........................................................Passed
+> Trim Trailing Whitespace.................................................Failed
+> - hook id: trailing-whitespace
+> - exit code: 1
+> - files were modified by this hook
+>
+> Fixing path/to/changed/files/file.txt
+>
+> codespell................................................................Passed
+> style-files..........................................(no files to check)Skipped
+> readme-rmd-rendered..................................(no files to check)Skipped
+> use-tidy-description.................................(no files to check)Skipped
+ +In the example above, one of the hooks modified a file in the proposed commit, +so the pre-commit check failed. You can run `git diff` to see the changes that +pre-commit made and `git status` to see which files were modified. To proceed +with the commit, re-add the modified file(s) and re-run the commit command: + +```sh +git add path/to/changed/files/file.txt +git commit -m 'feat: create function for awesome feature' +``` + +This time, all the hooks either passed or were skipped +(e.g. hooks that only run on R code will not run if no R files were +committed). +When the pre-commit check is successful, the usual commit success message +will appear after the pre-commit messages showing that the commit was created. + +> Check for added large files..............................................Passed
+> Fix End of Files.........................................................Passed
+> Trim Trailing Whitespace.................................................Passed
+> codespell................................................................Passed
+> style-files..........................................(no files to check)Skipped
+> readme-rmd-rendered..................................(no files to check)Skipped
+> use-tidy-description.................................(no files to check)Skipped
+> Conventional Commit......................................................Passed
+> [iss-10 9ff256e] feat: create function for awesome feature
+> 1 file changed, 22 insertions(+), 3 deletions(-)
+ +Finally, push your changes to GitHub: + +```sh +git push +``` + +If this is the first time you are pushing this branch, you may have to +explicitly set the upstream branch: + +```sh +git push --set-upstream origin iss-10 +``` + +> Enumerating objects: 7, done.
+> Counting objects: 100% (7/7), done.
+> Delta compression using up to 10 threads
+> Compressing objects: 100% (4/4), done.
+> Writing objects: 100% (4/4), 648 bytes | 648.00 KiB/s, done.
+> Total 4 (delta 3), reused 0 (delta 0), pack-reused 0
+> remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
+> remote:
+> remote: Create a pull request for 'iss-10' on GitHub by visiting:
+> remote: https://github.com/CCBR/reneeTools/pull/new/iss-10
+> remote:
+> To https://github.com/CCBR/reneeTools
+>
+> [new branch] iss-10 -> iss-10
+> branch 'iss-10' set up to track 'origin/iss-10'.
+ +We recommend pushing your commits often so they will be backed up on GitHub. +You can view the files in your branch on GitHub at +`https://github.com/CCBR/reneeTools/tree/` +(replace `` with the actual name of your branch). + +### Create the PR + +Once your branch is ready, create a PR on GitHub: + + +Select the branch you just pushed: + +![Create a new PR from your branch](./img/new-PR.png) + +Edit the PR title and description. +The title should briefly describe the change. +Follow the comments in the template to fill out the body of the PR, and +you can delete the comments (everything between ``) as you go. +When you're ready, click 'Create pull request' to open it. + +![Open the PR after editing the title and description](./img/create-PR.png) + +Optionally, you can mark the PR as a draft if you're not yet ready for it to +be reviewed, then change it later when you're ready. + +### Wait for a maintainer to review your PR + +We will do our best to follow the tidyverse code review principles: +. +The reviewer may suggest that you make changes before accepting your PR in +order to improve the code quality or style. +If that's the case, continue to make changes in your branch and push them to +GitHub, and they will appear in the PR. + +Once the PR is approved, the maintainer will merge it and the issue(s) the PR +links will close automatically. +Congratulations and thank you for your contribution! + +### After your PR has been merged + +After your PR has been merged, update your local clone of the repo by +switching to the main branch and pulling the latest changes: + +```sh +git checkout main +git pull +``` + +It's a good idea to run `git pull` before creating a new branch so it will +start from the most recent commits in main. + +## Helpful links for more information + +- This contributing guide was adapted from the [tidyverse contributing guide](https://github.com/tidyverse/tidyverse/blob/main/.github/CONTRIBUTING.md) +- [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) +- [tidyverse style guide](https://style.tidyverse.org) +- [tidyverse code review principles](https://code-review.tidyverse.org) +- [reproducible examples](https://www.tidyverse.org/help/#reprex) +- [R packages book](https://r-pkgs.org/) +- packages: + - [usethis](https://usethis.r-lib.org/) + - [devtools](https://devtools.r-lib.org/) + - [testthat](https://testthat.r-lib.org/) + - [styler](https://styler.r-lib.org/) + - [roxygen2](https://roxygen2.r-lib.org) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7aac86f..bc679fa 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,19 +1,16 @@ ## Changes ## Issues - - ## PR Checklist @@ -22,6 +19,6 @@ when referring to the issue. - [ ] This comment contains a description of changes with justifications, with any relevant issues linked. - [ ] Write unit tests for any new features, bug fixes, or other code changes. -- [ ] Update the docs if there are any API changes (roxygen comments, vignettes, readme, etc.). -- [ ] Update `NEWS.md` with a short description of any user-facing changes and reference the PR number. Guidelines: https://keepachangelog.com/en/1.1.0/ +- [ ] Update the docs if there are any API changes (roxygen2 comments, vignettes, readme, etc.). +- [ ] Update `NEWS.md` with a short description of any user-facing changes and reference the PR number. Follow the style described in - [ ] Run `devtools::check()` locally and fix all notes, warnings, and errors. diff --git a/.github/img/GitHub-Flow_bg-white.png b/.github/img/GitHub-Flow_bg-white.png new file mode 100644 index 0000000..03696c2 Binary files /dev/null and b/.github/img/GitHub-Flow_bg-white.png differ diff --git a/.github/img/create-PR.png b/.github/img/create-PR.png new file mode 100644 index 0000000..d0f8765 Binary files /dev/null and b/.github/img/create-PR.png differ diff --git a/.github/img/new-PR.png b/.github/img/new-PR.png new file mode 100644 index 0000000..1c6173f Binary files /dev/null and b/.github/img/new-PR.png differ diff --git a/.github/workflows/techdev-project.yml b/.github/workflows/techdev-project.yml new file mode 100644 index 0000000..e33449f --- /dev/null +++ b/.github/workflows/techdev-project.yml @@ -0,0 +1,18 @@ +name: Add issues/PRs to the TechDev project + +on: + issues: + types: + - opened + pull_request: + types: + - opened + +jobs: + add-to-project: + runs-on: ubuntu-latest + steps: + - uses: actions/add-to-project@v1.0.2 + with: + project-url: https://github.com/orgs/CCBR/projects/17 + github-token: ${{ secrets.ADD_TO_PROJECT_PAT }} diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 2c5bb50..fefc52e 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -8,6 +8,8 @@ on: name: test-coverage +permissions: read-all + jobs: test-coverage: runs-on: ubuntu-latest @@ -15,7 +17,7 @@ jobs: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-r@v2 with: @@ -23,28 +25,37 @@ jobs: - uses: r-lib/actions/setup-r-dependencies@v2 with: - extra-packages: any::covr + extra-packages: any::covr, any::xml2 needs: coverage - name: Test coverage run: | - covr::codecov( + cov <- covr::package_coverage( quiet = FALSE, clean = FALSE, - install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package") + install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package") ) + covr::to_cobertura(cov) shell: Rscript {0} + - uses: codecov/codecov-action@v4 + with: + fail_ci_if_error: ${{ github.event_name != 'pull_request' && true || false }} + file: ./cobertura.xml + plugin: noop + disable_search: true + token: ${{ secrets.CODECOV_TOKEN }} + - name: Show testthat output if: always() run: | ## -------------------------------------------------------------------- - find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true + find '${{ runner.temp }}/package' -name 'testthat.Rout*' -exec cat '{}' \; || true shell: bash - name: Upload test results if: failure() - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: coverage-test-failures path: ${{ runner.temp }}/package diff --git a/.github/workflows/auto_add_issues_to_user_kanban.yaml b/.github/workflows/user-projects.yml similarity index 100% rename from .github/workflows/auto_add_issues_to_user_kanban.yaml rename to .github/workflows/user-projects.yml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index baf04fc..3f0c4c0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -28,11 +28,6 @@ repos: - id: style-files - id: readme-rmd-rendered - id: use-tidy-description - # general linting - - repo: https://github.com/pre-commit/mirrors-prettier - rev: v2.7.1 - hooks: - - id: prettier # enforce commit format - repo: https://github.com/compilerla/conventional-pre-commit rev: v2.3.0 diff --git a/CITATION.cff b/CITATION.cff index d1f193d..7e68b97 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -19,6 +19,10 @@ authors: given-names: Kelly email: kelly.sovacool@nih.gov orcid: https://orcid.org/0000-0003-3283-829X + - family-names: Sevilla + given-names: Samantha + email: samantha.sevilla@nih.gov + orcid: https://orcid.org/0000-0002-8734-9875 repository-code: https://github.com/CCBR/reneeTools url: https://ccbr.github.io/reneeTools/ contact: diff --git a/DESCRIPTION b/DESCRIPTION index 97eb163..4ba7df1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -6,6 +6,8 @@ Authors@R: c( comment = c(ORCID = "0000-0001-8978-8495")), person("Kelly", "Sovacool", , "kelly.sovacool@nih.gov", role = "aut", comment = c(ORCID = "0000-0003-3283-829X")), + person("Samantha", "Chill", , "samantha.chill@nih.gov", role = "aut", + comment = c(ORCID = "0000-0002-8734-9875")), person("CCR Collaborative Bioinformatics Resource", role = "cph") ) Description: TODO What the package does (one paragraph). diff --git a/README.Rmd b/README.Rmd index c91e9d8..d27289c 100644 --- a/README.Rmd +++ b/README.Rmd @@ -32,6 +32,7 @@ You can install the development version of reneeTools from [GitHub](https://gith devtools::install_github("CCBR/reneeTools") ``` + + +## Help & Contributing + +Come across a **bug**? Open an [issue](https://github.com/CCBR/reneeTools/issues) and include a minimal reproducible example. + +Have a **question**? Ask it in [discussions](https://github.com/CCBR/reneeTools/discussions). + +Want to **contribute** to this project? Check out the [contributing guidelines](.github/CONTRIBUTING.md). + +## Development Roadmap + +![](./man/figures/reneeTools-development-plan.png) + +- [dev spreadsheet](https://nih-my.sharepoint.com/:x:/g/personal/homanpj_nih_gov/ETvHXgnwxExEpcP57Jj9_EwBHBvZBqNuZ_c3eu51w-SlnA?e=PcXKU8) +- [project board](https://github.com/orgs/CCBR/projects/32) diff --git a/README.md b/README.md index e42110a..5689143 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # reneeTools @@ -16,17 +17,37 @@ sequencing analysis pipeline You can install the development version of reneeTools from [GitHub](https://github.com/) with: -```r +``` r # install.packages("devtools") devtools::install_github("CCBR/reneeTools") ``` + + +## Help & Contributing + +Come across a **bug**? Open an +[issue](https://github.com/CCBR/reneeTools/issues) and include a minimal +reproducible example. + +Have a **question**? Ask it in +[discussions](https://github.com/CCBR/reneeTools/discussions). + +Want to **contribute** to this project? Check out the [contributing +guidelines](.github/CONTRIBUTING.md). + +## Development Roadmap + +![](./man/figures/reneeTools-development-plan.png) + +- [dev + spreadsheet](https://nih-my.sharepoint.com/:x:/g/personal/homanpj_nih_gov/ETvHXgnwxExEpcP57Jj9_EwBHBvZBqNuZ_c3eu51w-SlnA?e=PcXKU8) +- [project board](https://github.com/orgs/CCBR/projects/32) diff --git a/man/figures/reneeTools-development-plan.png b/man/figures/reneeTools-development-plan.png new file mode 100644 index 0000000..e8a06a4 Binary files /dev/null and b/man/figures/reneeTools-development-plan.png differ