Skip to content

Development Workflow

Jump to bottom
Christopher Carroll Smith edited this page Feb 1, 2025 · 5 revisions

Issue Resolution

The typical workflow to resolve issues is as follows:

  1. Create an issue on GitHub where you briefly describe the intended changes and their goals. Tag persons from which you might need additional inputs or approvals in the issue description text (they should get an email). You can get feedback as early as possible, not just when you create the pull request.
  2. In the issue, click on "Create a branch for this issue or link a pull request" to create a new branch. Click on "Open the branch with GitHub Desktop" to automatically switch your local repo to the new branch. Otherwise, you could end up developing in the wrong brach, which is annoying.
  3. Implement code changes.
      1. If you are confident that you did the right thing, you can proceed with preparing the PR for review (see next steps).
      1. If you are still unsure, you can create a PR in "Draft mode".
  4. Check your code formatting with lintr::lint_package() and get rid of any markers that it creates. Otherwise, the corresponding GitHub Actions workflow fails in the PR and you cannot merge.
  5. Check your code coverage with cov <- covr::package_coverage() and print cov to hopefully see 100% test coverage of the code even after your changes. If you want to get markers, call covr::zero_coverage(cov) and get rid of all the markers. Note that the idea of unit tests is to replicate all conditions such that all code is executed at least once in any test. Maybe you can even remove redundant conditions at this stage.
  6. Run devtools::check()
  7. Push your code changes to the PR and change it to review mode when you are ready.
  8. Get the approval of at least one person.
  9. Make sure that your PR is up to date with the main branch.
  10. Merge the PR to main.

CRAN Releases

In your local R project, run usethis::use_release_issue(version="x.x.x"), replacing the Xes with your target version number. This will create a Github issue with a release checklist. (Ultimately we may want to create our own release checklist, because in my opinion there are some problems with the auto-generated one.)

The items are grouped into three groups.

The first group

Create a new branch for your version release. On this branch, complete the first set of checklist items.

You should do usethis::use_version() as part of the first group of checklist items rather than the second, as the checklist wants. Otherwise, your CRAN check may complain about having a development version number.

You can skip the usethis::use_github_links() item. (It will ask if you want to overwrite the URL field; you should say no.) The urlchecker::url_check() will probably raise an alert about a broken URL.

As long as the URL passes a manual check (that is, you're able to navigate to it in your browser), you can ignore it. It's just because the automated URL checker doesn't like dynamically rendered websites.

When done, open a pull request from your branch on Github and merge to main. (If the pull request is linked to the release issue, it may close the issue, and you may need to reopen it.)

In your local R project, navigate to the main branch and run a git pull.

The second group

Then complete the second group of checklist items. In cran-comments.md, paste your R CMD check results, explain any unresolved notes that you think are false alarms, and indicate that you have resolved any requested changes from the CRAN maintainers.

Wait for CRAN notice of acceptance.

The third group

Now complete the third group of checklist items. When you run devtools::submit_cran(), a CRAN-SUBMISSION file will be created. This doesn't get committed to version control, but you shouldn't manually delete it.

After the submission is accepted to CRAN, run usethis::use_github_release() to create a Github release. This uses information from CRAN-SUBMISSION and will auto-delete that file when done.

Clone this wiki locally