The develop branch

All development should be done in the develop branch of the package GithHub repository. The aim should be to have a workable version in develop branch, so make sure your package passes R CMD check locally before pushing to the develop branch.

The main branch

The head of the main branch should be the latest released version of the package. No changes should be directly pushed to the main branch.

Continuous integration

All branches are monitored by Github Actions. Github Actions is a continuous integration system, meaning that any change pushed to one of the branches triggers the package to be built, and R CMD check to be performed. Any warnings or errors that occur during this process will cause an e-mail to be sent to the package maintainers. To implement continuous integration using Github Actions HADES package maintainers need to

  1. From the EvidenceSynthesis repo, copy these files into the new repository in their respective subfolders:

    • .github/workflows/R_CMD_check_Hades.yaml
    • .github/workflows/nightly_cleanup_Hades.yaml
    • compare_versions
    • deploy.sh

  2. Add these lines to your .Rbuildignore file if they are not already there:

    .github
deploy.sh
compare_versions

  3. Add a build status badge to README.md: [![Build Status](https://github.com/OHDSI/<reponame>/workflows/R-CMD-check/badge.svg)](https://github.com/OHDSI/<reponame>/actions?query=workflow%3AR-CMD-check)

  4. git add, git commit, and git push the new files.

  5. Ensure that Github Actions are executing by visiting: https://github.com/OHDSI/<reponame>/actions

Version numbering

Each package has a three-digit version number.

  • New micro versions (e.g. from 4.3.2 to 4.3.3) indicate bug fixes only. No new functionality, and forward and backward compatibility are guaranteed

  • New minor versions (e.g. from 4.3.3 to 4.4.0) indicate added functionality. Only backward compatibility is guaranteed

  • New major versions (e.g. from 4.4.0 to 5.0.0) indicate major revisions. All bets are off in terms of compatibility

Creating a release

Only the package maintainer may create a new release. The release should be prepared in the develop branch. The following steps are mandatory:

  1. Update the package meta-data

    • Update the package version number in the DESCRIPTION file.
    • Update the date in the DESCRIPTION file.
    • Ensure the Remotes section in the DESCRIPTION file only references the main branch of repos.
    • Ensure no Git tag or GitHub release with the new version number already exist. Delete them if they do.

  2. Regenerate the documentation. This includes the following steps. Note that the extras/PackageMaintenance.R file should contain the code needed to perform most of these steps:

    • Run roxygen to regenerate the manual files.
    • Perform a spellcheck using devtools::spellcheck()
    • Regenerate the package manual PDF.
    • Regenerate any vignette PDFs.
    • Regerate the package website using pkgdown, and fix the HADES logo using OhdsiRTools::fixHadesLogo() after running pkgdown.

  3. Make sure the package passes R check without warnings, both locally and on Github Actions. Fix as many Notes as possible.

  4. For those packages that go into CRAN: Check the package using devtools::check_win_devel() and devtools::check_rhub(), and submit to CRAN using devtools::release().

  5. Once all these steps are completed and commited to the develop branch, the package can be released by merging develop into main.

    Pushing changes to the main branch where the version number in the DESCRIPTION file is higher than the current one will trigger the automated release process. If the package passes R check, the following steps are automatically performed:

    • A new release and tag are created in the GitHub repo with the version number.

    • The package is pushed to the OHDSI drat repo.

  6. Announce the new release on the OHDSI Forums HADES development announcements thread, providing a short summary of hte most important changes in the new release.