Skip to contents

How to contribute to Rgemini

We welcome contributions to Rgemini by all GEMINI team members.

To submit suggestions for bug fixes/enhancements, please create a new issue providing sufficient details about the bug report/feature request.

Code development

To make changes to the Rgemini codebase/documentation, please follow these steps:

  1. Create a new issue or assign yourself to an existing issue you want to work on.

  2. Create a new branch off develop. The branch name should contain the issue number.

  3. Commit all changes to this newly created branch and include the issue number in each commit message.

  4. Once you finish code development, add a new item at the top of NEWS.md concisely describing what’s changed.

  5. If appropriate, add unit tests in the tests/testthat/ directory. For bug fixes, it’s usually helpful to include a unit test for the identified bug.

  6. If adding new functions with new documentation, update the _pkgdown.yml file by adding the new function to the appropriate reference section. Note that the Rgemini repository currently has a CI/CD workflow to generate and commit documentation on any pushed commit, but devtools::document() can also be run during development to debug locally.

  7. Note that any new package data should be saved as a .rda file in the data/ directory, and should be documented with roxygen in data.R.

  8. Functions derived based on published articles (e.g. clinical scores) should include a references section in roxygen. The citation format is: 1st_author_last_name 1st_author_initial, et al. Journal Abbreviation, Year. https://doi.org/xxxx.. URLs should be presented as-is without hyperlinking and DOI URLs should be used whenever possible. Note that commonly known online resources (e.g. links CIHI documentations, data dictionary) might not require a references section and can be included as hyperlinks in any roxygen section.

  9. Submit a pull request (PR) into the develop branch.

  10. Ask a team member to review the changes (see guidelines for reviewers below) and implement additional changes based on the reviewer’s feedback.

  11. Once the reviewer has approved the pull request, resolve any merge conflicts and CI/CD errors.

  12. Finally, squash all commits (confirm the PR # is referenced in the squash commit message) and merge the branch into develop, close the issue, and delete the branch you developed on.

Reviewing code

All pull requests (PRs) should be carefully reviewed by at least one person. For detailed instructions on what to look out for during review, please refer to the Code Review Checklist.

Briefly, when reviewing code:

  1. Assign yourself as reviewer for this PR (go to “Pull requests” -> click on the PR -> click on “assign yourself” under “Reviewers”).

  2. Pull the updated code from the branch associated with the issue. You can also install the package from a specific branch using remotes::install_github("GEMINI-Medicine/Rgemini@<branch_name>")

  3. Make sure that you can run the code without error messages. Check that it produces the expected outcome and resolves the issue.

  4. If possible, review each line of code that has been changed/added and provide feedback on anything you think could be improved. To comment on individual lines of code, go to “Pull requests” -> click on the PR -> “Files changed” -> + to add your comments.

  5. You can also share general feedback when you submit your review, or use the “Conversation” section of the PR to discuss open questions with the developer throughout the review process.

  6. Please share all feedback on GitHub (instead of slack/email) for transparency and to make sure previous discussions are well documented.

  7. As a reviewer, you usually should not push any changes to the code yourself, but instead, mention any suggestions in your review and the developer will be responsible for implementing the changes.

  8. Once the developer has addressed your comments, approve the pull request (the developer will then merge the PR and close the issue).

Merging into master

We typically accumulate multiple changes on the develop branch before merging all changes into master and updating the package version number.

At least one person should review the pull request into master and should run the following final checks before approval:

  1. Check whether there are any changes on master that are not yet on develop. If yes, merge master into develop.

  2. Make sure all changes on develop are summarized in NEWS.md.

  3. If new functions have been added, make sure they are listed in _pkgdown.yml.

  4. Decide on a new version number based on the guidelines here.

  5. Update the version number in the NEWS.md and DESCRIPTION files.

  6. Run devtools::document() in R to make sure all documentation is up to date.

  7. Run rcmdcheck::rcmdcheck() or devtools::check() and make sure no errors or warnings are returned.

  8. If everything looks good, approve the pull request and merge develop into master (without squashing commits).

  9. Add a new tag to the repository corresponding to the updated version number.

  10. Notify the team about the updated version. Ideally, all members should immediately update to the newest version of Rgemini.

  11. Update for HPC4Health users: Download the tar.gz file of the newest package version and save it in R:/GEMINI/HPC4Health/Rgemini versions/. Submit a request on the HPC4Health File Transfer Log for the package file to be transferred to /mnt/nfs/pkgs/GEMINI/. Ask the systems team to send out an email to all HPC4Health users announcing the new release.