Contributing guidelines

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 comes with a CI setup out of the box. On rhino::init() it creates a rhino-test.yml file, a GitHub Actions workflow which automatically runs all linters and tests once the project is pushed to GitHub.

To test rhino-test.yml itself, we have the app-push-test.yml workflow. It initializes a fresh Rhino application and pushes it to the bot/app-push-test branch. Then rhino-test.yml of this application 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 for any branch via the Actions tab.

The workflow requires a fine-grained personal access token with write access to code and workflows. It should be saved as the APP_PUSH_TEST_PAT repository secret.

Website

The documentation site is built and deployed automatically by our pkgdown.yml workflow. It is triggered on each push to the main branch. It runs the pkgdown/build.R script which builds the documentation for all Rhino versions listed in pkgdown/versions.yml.

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. Create a migration guide.
      • Refer to NEWS.md for hints on what to include in the guide.
    4. 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.
    5. 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 the new version to pkgdown/versions.yml.
    2. Add a development version .9000 in DESCRIPTION.
    3. Update NEWS.md:
      • Add a # rhino (development version) header.
      • Link the # rhino X.Y.Z header to the GitHub release.
      • Add a link to the migration guide in NEWS.md.
  3. Announce the release on #proj-rhino.
  4. Complete the upgrade of Rhino Showcase.

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.
    • Namely, NEWS.md is updated and if applicable contains a hint on how to migrate.