Skip to contents

Setting up checklist for a package

Source: vignettes/getting_started.Rmd
getting_started.Rmd

Where do you want to set-up checklist?

  1. I want to create a new R package from scratch.
  2. I want to use or update checklist in an existing R package.

Go to vignette("getting_started_project", package = "checklist") when you want to use checklist on a project.

Starting an R package from scratch

Prepare online setup

  1. Go to https://github.com and login. Create a new public repository in the INBO organisation. Use the package name as repository name. Enter the repository name and optionally a description. Don’t add a README, .gitignore or LICENSE.

Local setup

  1. Install or update the checklist package with remotes::install_github("inbo/checklist").
  2. Use checklist::create_package(). You’ll need to provide the package name, title, description and maintainer. Please read the documentation of create_package() prior to running the function. The function creates an RStudio project with a the package template in a folder with the name of the package.
  3. Open the newly created RStudio project.
  4. In the Build pane, select More > Configure Build Tools. Click the Configure button and add a tick to Install and Restart. All boxes except Vignettes must be ticked. Close the two dialogue boxes by clicking the OK buttons (once for each of box).
  5. Open the README.Rmd file and update the content. Knit the file and stage the README.Rmd and README.md files.
  6. Review and commit the changes into an initial commit.
  7. Add at least one function to the package.
  8. Build the package.
  9. Run x <- checklist::check_package(). Fix any issues that arise during the checks. Repeat the last two steps until you end up with only a single new note about a New submission.
  10. Run checklist::write_checklist(x). This functions can convert some ‘new’ warnings and notes into ‘allowed’ warnings and notes.
  11. Run x <- checklist::check_package() again to check that only ‘allowed’ warnings and notes remain. Repeat the last four steps until you get No problems found at the end of the checklist output.
  12. Commit any remaining changes.
  13. Run in the git terminal the command git remote add origin git@github.com:inbo/_your_package_name_.git where you replace _your_package_name_ with the actual repository name.
  14. Run in the terminal the command git push -u origin main. This will run the checklist test on GitHub for the first time. An orange circle, green thick mark or red cross will appear next to the latest commit or PR.

Finalise online setup

  1. Go to https://about.codecov.io and login with your GitHub account. Search for your package repository in the INBO organisation. Copy the token.
  2. Go to your package repository on GitHub. Choose Settings > Secrets. Add New repository secret with name CODECOV_TOKEN and the token you copied as value.
  3. Wait for all tests to finish (either green thick or red cross).
  4. Go in your package GitHub repository to Settings > Branches. Add rule for Branch name pattern main and select the following items and Save changes.
    • Require status checks to pass before merging
    • Require branches to be up to date before merging
    • Status checks found in the last week for this repository
      • check package
      • macOS-latest (release)
      • ubuntu (oldrel)
      • ubuntu (devel)
      • windows (release)
  5. Go in your package GitHub repository to Settings > Pages. Select Deploy for branch as source, gh-pages as branch and save the changes.

Get it working with an existing package or update the checklist

Prerequisites

  1. Make sure the package is using git as version control system.
  2. The git status must be clean. You’ll need to commit all changes first. It is OK to have Untracked files.
  3. You need a public remote git repository at https://github.com/inbo.

Local setup

  1. Install the checklist package with remotes::install_github("inbo/checklist").
  2. Run checklist::setup_package(). This will add and/or modify files. Inspect the modified files, especially if you are updating to a new checklist version and made some tweaks in the past.
  3. Commit the changes.
  4. Run x <- checklist::check_package() and fix any issues. Repeat this step until you have only issues that are not a problem. Commit any remaining changes.
  5. Update the checklist.yml with checklist::write_checklist(x). This function will ask you which (if any) of the current allowed warnings and notes you want to keep. Then it asks which warnings and notes you want to allow. You’ll need to motivate each of them.
  6. Run x <- checklist::check_package(). This should run without returning an error.

Online setup

  1. Go to https://about.codecov.io and login with your GitHub account. Search for your package repository in the INBO organisation. Copy the token.
  2. Go to your package repository on GitHub. Choose Settings > Secrets. Create a new repository secret with name CODECOV_TOKEN and the token you copied as value.
  3. Push changes from your local repository to GitHub. This will start the checks on GitHub. An orange circle, green thick mark or red cross will appear next to the latest commit or PR. Wait for all tests to finish (either green thick or red cross).
  4. Go in your package GitHub repository to Settings > Branches. Add rule for Branch name pattern main and select the following items and Save changes.
    • Require status checks to pass before merging
    • Require branches to be up to date before merging
    • Status checks found in the last week for this repository
      • check package
      • macOS (release)
      • ubuntu (oldrel)
      • ubuntu (devel)
      • windows (release)
  5. Go in your package GitHub repository to Settings > Pages. Select Deploy for branch as source, gh-pages as branch and save the changes.

Troubleshooting

Failing status check check package

Sometimes the check package GitHub Action (GHA) may fail for other reasons than failure of one or more of the checks executed by checklist::check_package(). This is likely due to a missing dependency when the action tries to install R packages. In that case, the GHAs, check_on_branch.yml and check_on_main.yml files need to be modified so the missing dependency can be installed. To diagnose if this is the case when an action failed, you can follow these steps:

  • Go to the check package GHA with a red cross (indicating failure) and click on the details link. You will be directed to an overview of all steps that were taken in the action. The page will scroll automatically to where the final error occurs.
  • Check if you see an error that looks like:
    • ERROR: dependency 'sf' is not available for package 'inborutils'
    • ERROR: package installation failed
  • If this is the case, make a mental note of which package(s) failed to install.
  • Next, open the raw logs by clicking on the gear icon and then View raw logs.
  • Search the log (CTRL+F) using the name of the package or more specifically search for installing *source* package '<packagename>'. Also try searching for error:, failed and deb:.
    • It is likely that you detect that it is actually a dependency R package that failed to install and that this failing installation was due to a missing system dependency.
      • For instance, in the example above, the culprit was that the R package units - which is a dependency of sf - failed to install, because it depended on the system dependency libudunits2-dev
      • The easiest way to detect this, is to search for deb:. Here is a snippet of what you might see:
      Configuration failed because libudunits2.so was not found. Try installing:
 * deb: libudunits2-dev (Debian, Ubuntu, ...)
 * rpm: udunits2-devel (Fedora, EPEL, ...)
 * brew: udunits (OSX)

To fix this problem in the check_on_branch.yml and check_on_main.yml files, install it with the aptget command:

```
    steps:
      - uses: inbo/actions/check_pkg@master
        with:
          aptget: libudunits2-dev
```

In case you need multiple aptget dependencies, add them to a single aptget item separated with a space.

```
    steps:
      - uses: inbo/actions/check_pkg@master
        with:
          aptget: libudunits2-dev libpoppler-cpp-dev
```

Add, commit and push these changes so they take effect in the GHAs.