Contributing to gsmApp
Source:.github/CONTRIBUTING.md
This outlines how to propose a change to gsmApp.
Fixing typos
You can fix typos, spelling mistakes, or grammatical errors in the documentation directly using the GitHub web interface, as long as the changes are made in the source file. This generally means you’ll need to edit roxygen2 comments in an .R
, not a .Rd
file. You can find the .R
file that generates the .Rd
by reading the comment in the first line.
Bigger changes
Prerequisites
Before contributing code via a Pull Request, make sure to file an issue using one of the pre-specified issue templates. Choose the template that best categorizes what you aim to contribute, which generally can be one of the following:
- Bugfix Issue: Fix a bug in the code
- Feature Issue: Develop a new feature
- QC Issue: Update QC framework, including documentation, qualification, automation, etc.
Someone from the development team will decide if the issue is in scope. If so, the issue will be appropriately triaged and assigned to a core developer, or approval to submit a Pull Request associated with the submitted issue will be granted. If it is decided that the issue is out of scope or otherwise irrelevant, the issue will be closed.
The issue templates provide comments/prompts to help ensure that all relevant information is included. When submitting issues for bug fixes or specific feature requests, it is often helpful to provide a minimal reprex, or reproducible example, to help the core developers visualize the issue.
Suggestions or other input that might not warrant formal submission of an issue can be filed under discussions, which can help facilitate discourse of specific use-cases or requests.
Branches
The core branches that are used in this repository are:
-
main
: Contains the production version of the package. -
dev
: Contains the development version of the package. -
fix-XXXX
: Used to develop new functionality in the package. See Development Process below for more details. -
release
: Used to conduct regression testing and finalize QC documentation for a release. See Release Process below for more details.
Development Process
All code development takes place in fix
branches. This section provides general guidance about this process flow. A detailed step-by-step workflow for code development in fix
branches can be found in the first section of Appendix 1 below.
Once an issue is filed and delegated to a core developer, a fix
branch will be opened, which is where all package development related to that issue will be conducted. Each fix
branch should be linked to one or more of the filed GitHub issue(s). The issue(s) will be referenced in the naming of the fix
branch. For example, a branch named fix-111
addresses issue #111. Tasks related to documentation, testing, and/or qualification may also use fix
branches and associated issues.
In addition to the above, please also use the following general guidelines when creating a Pull Request:
- New code should generally follow the tidyverse style guide, but automatic styling will be applied before each release. More details about the style guide can be found here.
- Documentation should be included, using the roxygen2 package.
- New functions or changes to existing functions should include updated unit tests to demonstrate branch compatibility. Core developers request that unit tests are developed using testthat >= v3.0.0.
- Please include any relevant details that will provide context for the proposed updates or new functionality. Additionally, link the Pull Request to the relevant issue(s) by using either closing keywords, or the
Development
section on the sidebar of the Pull Request page. - In general, all Pull Requests should target the
dev
branch (with the exception of a release Pull Request). - All checks and tests must be passing before merging a Pull Request to
dev
. These checks are automatically run via GitHub Actions, as described in Appendix 3, but you can also run them locally by callingdevtools::check()
on yourfix
branch before finalizing a Pull Request.
Release Process
Code release follows a process using release
branches. A release is initiated when all feature development, QC, and qualification has been completed for a given functionality. The primary objective of the Release Workflow is to conduct regression testing and finalize all QC documentation for that release. A detailed step-by-step workflow for code release can be found in the second section of Appendix 1 below.
Style Guide
Code developers for gsmApp use the tidyverse style guide with minimal modifications. The code below is run to standardize styling before each release:
double_indent_style <- styler::tidyverse_style()
double_indent_style$indention$unindent_fun_dec <- NULL
double_indent_style$indention$update_indention_ref_fun_dec <- NULL
double_indent_style$line_break$remove_line_breaks_in_fun_dec <- NULL
styler::style_dir('R', transformers = double_indent_style)
styler::style_dir('tests', recursive = TRUE, transformers = double_indent_style)
Imports
We recommend reading the Dependencies: In Practice chapter of R Packages 2e before adding any dependencies to this package. Some specific guidelines:
- Do not add a dependency for something that can be done relatively easily in base R. This is a fine line, so it’s acceptable to err on the side of adding the dependency; we can help with the work needed to avoid the dependency.
- If a package is only needed for specific functions that won’t be called by many/most users, call
usethis::use_package(pkg, "Suggests")
, and follow the instructions for making your code inform users to install the required package. - If a package is used by most/all users, call
usethis::use_package(pkg)
to make sure the package is in theImports:
section of theDESCRIPTION
. This will also “elevate” the package fromSuggests:
toImports:
if it is already used in that manner. - Do not use
@import
or@importFrom
directly in a function’s {roxygen2} block. - If the imported function is an infix (like
%||%
) or is used in a “tight loop” that could conceivably be called millions of times, useusethis::use_import_from(pkg, function)
to import the function. - Other functions should be namespaced using
pkg::function()
. This makes it easier to find where the dependency is used, in case we want or need to reduce our dependency footprint. - In rare cases, we might want to
usethis::use_import_from()
other frequently used functions, or even@import
an entire package. If you believe this should happen in your code, please explain why in your pull request.
Appendix 1 - Detailed Workflows
fix
Branch Workflow
- Create issue(s) defining addition(s) and/or revision(s):
- Select the appropriate template to use (should be one of the following):
Bugfix Issue
Feature Issue
QC Issue
- Assign issue(s) to core developer(s).
- Assign milestone within issue(s).
- Select the appropriate template to use (should be one of the following):
- Developer creates
fix
branch (with nomenclature reflecting associated issue(s)) and updates the associated code(s). - Developer opens Pull Request for the
fix
branch to be merged into thedev
branch using the GitHub default Pull Request template. Developer should do the following:- Assign Pull Request to self.
- Requests review(s).
- Assign milestone.
- Link to associated issue(s).
- Before the
fix
branch can be merged into thedev
branch, the Pull Request must:- Be approved by assigned code reviewer(s).
- Pass all GitHub qualification checks.
-
fix
branch is merged into thedev
branch after the above requirements are fulfilled. The user who merges thefix
branch should make sure to delete it upon merging.
release
Branch Workflow
- Release Owner creates
release
branch fromdev
branch.- The
release
branch should be named according to the version of gsmApp being released (e.g.,release-v1.2.0
) using semantic versioning. - If a release branch is already created, make sure that it is synced with the current
dev
branch.
- The
- Release Owner prepares the release for QC by performing the following steps and pushing updates to the
release
branch:Confirm that the version in the
DESCRIPTION
file is up to date.Run
styler
using the script from the style guide above and commit any updates.Update
NEWS.md
with a summary of the revisions/additions in the release. Keep any information from previous releases to maintain traceability through versions.Ensure that the qualification specifications spreadsheet is up-to-date and accurate. If there have been any changes/updates to qualification tests, reach out to the qualification developer to update any necessary files.
If applicable, review
README.md
and relevant vignettes to make sure updates are accurately described.Ensure all unit tests are passing.
Check if all qualification tests are passing and if new features were added that need to be qualified. If updates are needed, they should be outlined in a release QC issue.
Run
devtools::spell_check()
and resolve findings.Build site using
pkgdown::build_site()
. Check that all examples are displayed correctly and that all new functions occur on the Reference page.Open a clean R session. Run
devtools::install()
and thendevtools::check()
locally and confirm that there are no issues/conflicts.
- Release Owner creates Pull Request from the
release
branch to themain
branch:- Use the release Pull Request template by adding
?template=release.md
to the URL when creating the Pull Request. The user can also click the link, then clickRaw
, and copy/paste the displayed Markdown into the Pull Request. - Assign Pull Request to self.
- Request QC review(s).
- Assign milestone.
- Complete Risk Assessments for each Assessment/Feature added as outlined in the Pull Request template.
- Create comments in the Pull Request with a unique QC checklist for each selected Assessment/Feature.
- Use the release Pull Request template by adding
- QC Reviewer(s) conduct(s) review by:
- Completing all QC checklists in the Pull Request.
- Ensuring all GitHub Actions on the Pull Request to the
main
branch are passing.
- QC Reviewer(s) approve(s) Pull Request or request(s) changes. If changes are needed:
- QC Reviewer(s) should file issues and the development team should follow the standard package development process using
fix
branches. - Once issues are resolved and merged to the
dev
branch, Release Owner can merge thedev
branch into therelease
branch, and re-request review. - If needed, the original Pull Request can be closed and a new release Pull Request can be created with a Release Candidate (RC) value added to the branch name (e.g.,
release-v1.2.0-RC2
)
- QC Reviewer(s) should file issues and the development team should follow the standard package development process using
- Once the Pull Request is approved, the Release Owner should complete the release by taking the following steps:
- Merge the release Pull Request to the
main
branch. - Create the GitHub release targeting the
main
branch using the wording fromNEWS.md
, in addition to the automatically generated content in GitHub. - Confirm that the QC Report is attached to release.
- Merge the release Pull Request to the
- Finally, the Release Owner (or qualified designee) should complete the following housekeeping tasks:
- Create a Pull Request to merge the
main
branch into thedev
branch to sync any updates that were made during release process. - Check that all issues associated with the current release are closed.
- Update the milestone for any incomplete tasks.
- Delete code branches associated with previous releases.
- Close the milestone and project associated with the previous release.
- Create a Pull Request to merge the
Appendix 2 - QC Checklist
This QC checklist is to be used as part of the Development and Release Workflows described above. When applied to an Assessment/Feature, confirm that each function meets the requirements described. When applied to utility or other functionality, use relevant sections of the checklist and modify QC checks as needed. A risk-based approach will be used to determine whether each release requires a high-level or detailed release QC.
Appendix 3 - Continuous Integration with GitHub Actions
GitHub Actions are used in gsmApp to automate processes and ensure all code and documentation is created consistently and documented thoroughly.
Merges to main
Branch
- R CMD Check (
R-CMD-check-main
):- Basic R CMD check which can be run using
rcmdcheck::rcmdcheck()
- This check will run on
ubuntu-latest
and on R version 4.1.3. Additionally, it will be run on the latest R release version onwindows-latest
,macOS-latest
, andubuntu-latest
.
- Basic R CMD check which can be run using
-
pkgdown
:- Builds the pkgdown site for gsmApp.
Code of Conduct
Please note that the gsmApp project is released with a Contributor Code of Conduct. By contributing to this project you agree to abide by its terms.