Skip to contents

Contributing guidelines

Source: .github/CONTRIBUTING.md

This document contains guidelines specific to Rhino. Appsilon’s general contributing guidelines still apply.

Development tools

  1. R CMD check
    devtools::check() or rcmdcheck::rcmdcheck()

  2. Run linter
    devtools::lint() or lintr::lint_package()

  3. Run unit tests
    devtools::test()or testthat::test_local()

  4. Check spelling
    devtools::spell_check() or spelling::spell_check_package()

  5. Build documentation
    devtools::build_site() or pkgdown::build_site()

  6. Build package
    devtools::build() or pkgbuild::build()

App Push Test

Rhino creates a .github/workflows/rhino-test.yml file on rhino::init(). This GitHub Actions workflow automatically runs all linters and tests once a project is pushed to GitHub. To test that it works correctly we have the App Push Test workflow.

The Push Test initializes a fresh Rhino application and pushes it to the bot/app-push-test branch. The Rhino Test of this application then runs and its results can be viewed in the list of workflow runs. The App Push Test is triggered automatically on pushes to main and can also be triggered manually.

Release process

Preparation

  1. Announce the planned release on #proj-rhino (approximate date and scope).
  2. Plan promotion (social media, blog post, …). Coordinate efforts with the marketing team.
  3. Ensure that the App Push Test passes (the latest run for the main branch should be green).
  4. Upgrade Rhino Showcase.
    1. Create a task to track progress.
    2. Test upgrade by installing Rhino from the current main branch.
    3. Continue the release process. The upgrade can be completed and the task closed once the package is accepted to CRAN.
  5. Prepare the package for release.
    1. Create a release-X.Y.Z branch from main.
    2. Update DESCRIPTION.
      • Bump the package version according to SemVer. Drop the development version (last component, e.g. .9001).
    3. Update NEWS.md.
      • Replace the (development version) with X.Y.Z in the header. Do not add a link to GitHub releases yet - the link won’t work and will fail CRAN checks.
      • Edit the list of changes to make it useful and understandable for our users. See keep a changelog for some guidelines.
    4. Submit the changes in a pull request titled “Release X.Y.Z”. Get it approved and merged.

Submitting to CRAN

  1. Build and test the package.
    1. Checkout the main branch and ensure it is up to date.
    2. Build the package with devtools::build().
    3. Test the package with R CMD check --as-cran rhino_X.Y.Z.tar.gz. There should be no errors, warnings nor notes.
  2. Publish a new pre-release on GitHub.
    1. Create a new vX.Y.Z-rc.1 tag on the main branch (rc stands for release candidate).
    2. Use the tag name for title.
    3. Leave description blank.
    4. Check “Set as a pre-release”.
    5. Click “Publish release”.
  3. Submit the package to CRAN.
    1. Use your own name and email.
    2. Click “Choose File” and select rhino_X.Y.Z.tar.gz from step 1.
    3. Click “Upload the package”.
    4. Click “Submit package”.
    5. Click the confirmation link sent to opensource@appsilon.com.
  4. If CRAN reviewers ask for changes, implement them and return to step 1. Use rc.2, rc.3 and so on for subsequent submissions.

Once accepted to CRAN

  1. Publish a new release on GitHub.
    1. Create a new vX.Y.Z tag on the main branch.
    2. Use the tag name for title.
    3. Fill in the description from NEWS.md.
    4. Check “Set as the latest release”.
    5. Click “Publish release”.
  2. Prepare the package for further development.
    1. Add a development version .9000 in DESCRIPTION.
    2. Add a # rhino (development version) header in NEWS.md.
    3. Link the # rhino X.Y.Z header to the GitHub release in NEWS.md.
  3. Announce the release on #proj-rhino.

Development process

  1. All changes are introduced in pull requests to the main branch, which must be always kept in a “potentially shippable” state.
  2. Pull requests must be peer-reviewed. The reviewer inspects the code, tests the changes and checks them against the DoD before approving.
  3. We follow the Semantic Versioning scheme. Starting with 1.0.0, all versions should be released to CRAN.

Definition of Done

  1. The PR has at least 1 approval and 0 change requests.
  2. The CI passes (R CMD check, linter, unit tests, spelling).
  3. The change is thoroughly documented.