Contributor Guidelines

Introduction

This page outlines the development process for gsm, including how to contribute by filing issues, bug reports, and submitting code via a Pull Request.

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: 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 calling devtools::check() on your fix branch before finalizing a Pull Request.
• During the development process, developers should verify that the qualification-dev-check Action runs successfully. This checks whether the qualification tests were executed successfully or failed. This can be verified by looking under the Checks tab of a given Pull Request - the status will read either “Success” or “Failure”. If there are any conflicts present or new functionality is added to code that is not covered by existing qualification tests, the developer submitting the Pull Request should add this information to the version qualification issue.

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 gsm 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)

Appendix 1 - Detailed Workflows

fix Branch Workflow

1. 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).
2. Developer creates fix branch (with nomenclature reflecting associated issue(s)) and updates the associated code(s).
3. Developer opens Pull Request for the fix branch to be merged into the dev 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).
4. Before the fix branch can be merged into the dev branch, the Pull Request must:
   • Be approved by assigned code reviewer(s).
   • Pass all GitHub qualification checks.
5. fix branch is merged into the dev branch after the above requirements are fulfilled. The user who merges the fix branch should make sure to delete it upon merging.

release Branch Workflow

1. Release Owner creates release branch from dev branch.
   • The release branch should be named according to the version of gsm 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.
2. 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.
     • After the version in the DESCRIPTION file is updated, run gsm::UpdateGSMVersion() to update metadata that includes the gsm version number.
   • Run styler using the script from the style guide above (or by running gutil::style_code()) 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 then devtools::check() locally and confirm that there are no issues/conflicts.
3. Release Owner creates Pull Request from the release branch to the main 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 click Raw, 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 (See example for v0.1.0).
4. 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.
5. 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 the dev branch into the release 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)
6. 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 from NEWS.md, in addition to the automatically generated content in GitHub.
   • Confirm that the QC Report is attached to release.
7. Finally, the Release Owner (or qualified designee) should complete the following housekeeping tasks:
   • Create a Pull Request to merge the main branch into the dev 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.

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.

High-Level QC Checklist

• Documentation
  • New functionality contains an @export tag.
  • New functionality contains an adequate level of documentation.
• Error Checking
  • New functionality has associated unit test(s).
  • Tests confirm that the input data has required columns (if any).
  • Tests confirm that the output data has expected columns/structure.
  • Tests confirm intended functionality for each parameter.
• Data Model
  • Running Make_Snapshot() using defaults returns no errors.
  • Running CheckSnapshotInputs() using the output of Make_Snapshot()$lSnapshot returns no errors.
  • Running Study_Assess() using defaults returns no errors.
  • Running Study_Report() using the output of Study_Assess() from above produces a HTML report that accurately displays results.
• Basic QC
  • Assessment has User Requirements + Qualification tests captured using qualification framework. A QC report is generated as expected and all checks pass successfully.
  • Code is well commented and easy to read/understand.
  • Qualification specifications spreadsheet (qualification_specs.csv) has been reviewed and approved by a qualification developer.
  • No file paths or other company-specific data are present.
  • devtools::check() passes with no errors/warnings/notes.
  • Package documents are up to date, and running devtools::document() does not change any files.
  • Codes use tidyverse best practices for standard data manipulation. If unclear, reviewer should start a discussion thread.
  • All new dependencies add significant value. If unclear, reviewer should start a discussion thread.
  • All GitHub Actions run with no errors.

Detailed QC Checklist

• Documentation
  • Function name captured in roxygen2 title (e.g., “Adverse Event Assessment”)
  • Assessment purpose captured in roxygen2 description (e.g., “Evaluates adverse event (AE) rates to identify sites that may be over- or under-reporting AEs”)
  • Input data requirements are captured in a dedicated roxygen2 details section under Data specification (#' @section Data specification, or # Data specification if storing data specification in a .md file).
  • Statistical methods and assumptions are captured in a dedicated roxygen2 details section under Statistical assumptions (#' @section Statistical assumptions, or # Statistical assumptions if storing statistical assumptions in a .md file). This section should link to the relevant Analyze_ function(s) for further details.
  • All function parameters are described with a @param tag. Each parameter description should include its name, type, purpose, usage details, default value (if applicable), requirement, and valid options (if applicable).
  • All external dependencies are captured. Use @importFrom _package_ _function_ when importing five (5) or fewer functions, and @import _package_ otherwise.
  • Function output is captured with a @return tag. Each output description should include output type, structure, and data specification (if applicable).
  • At least one (1) example is provided under an @examples tag.
• Error Checking
  • Basic checks for all parameters should be included using stopifnot() or similar logic (e.g., stopifnot("dfInput is not a data frame" = is.data.frame(dfInput)))
  • Tests confirm that stopifnot() parameter checks are working as expected.
  • Tests confirm that the input data has required columns (if any).
  • Tests confirm that the output data has expected columns/structure.
  • Tests confirm intended functionality for each parameter.
  • Tests confirm that missing data in required columns is handled appropriately and errors/warnings are produced if needed.
• Basic QC
  • Assessment has User Requirements + Qualification tests captured using qualification framework. A QC report is generated as expected and all checks pass successfully.
  • Code is well commented and easy to read/understand.
  • Qualification specifications spreadsheet (qualification_specs.csv) has been reviewed and approved by a qualification developer.
  • No file paths or other company-specific data are present.
  • Function called from non-tidyverse dependencies are called via ::.
  • devtools::check() passes with no errors/warnings/notes.
  • Package documents are up to date, and running devtools::document() does not change any files.
  • Codes use tidyverse best practices for standard data manipulation. If unclear, reviewer should start a discussion thread.
  • All new dependencies add significant value. If unclear, reviewer should start a discussion thread.
  • All GitHub Actions run with no errors.

Appendix 3 - Continuous Integration with GitHub Actions

GitHub Actions are used in gsm to automate processes and ensure all code and documentation is created consistently and documented thoroughly.

Merges to dev Branch

• R CMD Check (R-CMD-check-dev):
  • Basic R CMD check which can be run using rcmdcheck::rcmdcheck()
  • Provides an additional check for the ability to build the pkgdown reference index and ensure that all functions are documented correctly. This check will run on ubuntu-latest and on R version 4.1.3.
• Build Markdown (build-markdown):
  • Builds Assessment Specification tables from function documentation
  • Outputs are added to man/.md and any changes are committed to the compare branch or the triggering Pull Request.
• Test Coverage (test-coverage):
  • Uses covr to check the package coverage of gsm.
• Qualification Check (qualification-check-dev):
  • Runs the qualification tests but will not fail if any of the tests do not pass. Developers should review this check when changes that might need updates to qualification are done.

Merges to main Branch

• R CMD Check (R-CMD-check-main):
  • Basic R CMD check which can be run using rcmdcheck::rcmdcheck()
  • Provides an additional check for the ability to build the pkgdown reference index and ensure that all functions are documented correctly. The check will also run all qualification tests to ensure that the release is fully qualified. 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 on windows-latest, macOS-latest, and ubuntu-latest.
• pkgdown:
  • Builds the pkgdown site for gsm.
• Qualification Report (qualification-report):
  • Builds the qualification vignette as an attached artifact to the Pull Request. This should be reviewed by the Pull Request Owner for completeness and correctness to ensure that the artifact added to the release is correct.