Setting up checklist for a package

Where do you want to set-up checklist?

• I want to create a new R package from scratch.
• 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.

Note that checklist needs a lot of information to properly set up a package. We store the relevant information for later use. Since we often need the same information for multiple packages, storing this information saves a lot of time later when setting up other packages or projects.

The main text of this vignette focuses on how the functions interact assuming you have used them before. In case you use them for the first time, you get more questions. These are hidden in details sections. Click on the expand icons to read more about these questions.

Starting an R package from scratch

Prepare online setup

Go to https://github.com or another git provider and login. Create a new public repository in your 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

Install or update the checklist package with remotes::install_github("inbo/checklist").

Use checklist::create_package(). You’ll need to provide the package name and the path where to store to package. The function will ask you several questions to set up the package correctly. Try to ask them as accurately as possible, that will save you time later. Note that you can change most of the answers later on by modifying the DESCRIPTION file.

The function starts by asking you for a title, description and keywords. These will be used in the DESCRIPTION and README.Rmd file.

The next question is about the git repository. checklist lists the stored git organisations on your machine. You can select one of these or choose to create a new one.

Expand to see what happens during the first time you use checklist to create a package or project.

The function asks you to choose a preferred protocol (ssh or https). This choice will be stored for future use. Feel free to choose https if you don’t know what to choose.

Next it asks you for the git URL of your organisation. Select to organisation you want to use or choose new git organisation to create a new one. This will be the only option you get the first time. If you selected new git organisation, enter the git URL of your organisation. E.g. https://github.com/inbo for the inbo organisation on github. checklist will now look for a public checklist within your organisation and cache this on your machine. We strongly recommend that your organisation has such a public repository. See vignette("organisation", package = "checklist") on how and why to create such a repository.

If your organisation has no public checklist repository, the function will ask you to create a new list of organisations. A list of organisations consists of at least one organisation. You can reuse organisations already stored on your machine or you can create new ones.

For each organisation you need to provide at least an email and a name in some a language. This will be default name in case we need the name in a language that is not available. Next you can optionally provide the name in other languages. Then you can provide the URL to the organisations’ website, logo and ROR. For the time being, these are only used in the pkgdown website in the footer and the authors page. ROR stands for Research Organisation Registry. The Zenodo community identifier is a way to group your organisations’ research outputs on Zenodo. When you set the ORCID to required, then any person who’s email domain matches the organisation email will be required to provide an ORCID when adding themselves as author. We are almost getting there. Now you need to determine how this organisation deals with rights holders and funders. The options are:

• optional: no specific requirements.
• single: this organisation must be the single rights holder and or funder.
• shared: multiple rights holders or funders allowed but this organisation must be one of them.
• when no other: this organisation must be the rights holder or funder when no other organisation is specified.

Finally, you need to select the licenses that are allowed for this organisation. You must pick one or more licenses for packages, projects and data. When choosing a new license, you must provide both the abbreviation and a link to a markdown version of the license. checklist will automatically include that license text in the package when you select that license later on. The function will repeat this process until you indicate that you don’t want to add more organisations. Note that generating this list of organisations once an storing it in a checklist repository within your organisation save a lot of time for you co-workers.

In case the organisation allows for multiple licenses, the function will ask you to select one of the allowed licenses for the package.

Next, we ask for the main language of the package. This will be the default language for messages and documentation. check_spelling() will use this language as default to check the spelling.

Then we come to the packages authors. First select the package maintainer. checklist display the list of known persons on your machine. Select one of these or choose to add a new person. Note that the order depends on the usage frequency, so the most frequently used persons appear at the top of the list. Once selected, you get an detailed overview of the person’s information. Which you can use, update or you can select another person.

Expand to see how to add a new person

If you choose to add a new person, you need to provide a given name, family name and e-mail. Optionally, you can provide an ORCID and affiliation. When the e-mail domain matches one of the stored organisations on your machine, you can select that organisation as affiliation. If you select an organisation that requires an ORCID, you must provide one.

This process repeats until you indicated that you don’t want to add more authors.

You can add one or more rights holders and funders in a similar way as for the authors. However, now checklist uses the information from the list of organisations you created or selected earlier on. You still can add a new organisation at this point. If you choose to don’t add any rights holder or funder and the organisation required that it must be one of them, the function will silently add the default rights holder and funder.

Expand to see how to add a new organisation

When you need a different organisation as rights holder or funder, you can select other rights holder or other funder to add a new one. You get the same questions as when creating a new organisation earlier on.

The function will now create a new folder with the new package. The folder will contain a standard R package structure with several files and folders. The information you provided earlier on will be used to fill in the relevant fields in the DESCRIPTION file, README.Rmd, checklist.yml, organisation.yml and _pkgdown.yml.

In case you ran the function in an RStudio session, it opens the newly created package in a new RStudio project. 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).

Open the README.Rmd file and update the content.

Review and commit the changes into an initial commit.

Add at least one function to the package.

Build the package. Knit the file and stage the README.Rmd and README.md files.

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.

Run checklist::write_checklist(x). This functions can convert some “new” warnings and notes into “allowed” warnings and notes.

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.

Commit any remaining changes.

Run in the terminal the command git push -u origin main. This will push the code and, when on GitHub, run the checklist test for the first time. An orange circle, green thick mark or red cross will appear next to the latest commit or PR in GitHub.

Finalise online setup in GitHub

Go to https://about.codecov.io and login with your GitHub account. Search for your package repository in your GitHub organisation. Copy the token.

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.

Wait for all tests to finish (either green thick or red cross).

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)

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

Make sure the package is using git as version control system.

The git status must be clean. You’ll need to commit all changes first. It is OK to have Untracked files.

You need a public remote git repository.

Local setup

Install the checklist package with remotes::install_github("inbo/checklist").

Run checklist::setup_package(). This will add and/or modify files. Depending on the existing files and their information, the function will ask you several questions to set up the package correctly. They are similar to the questions asked when creating a new package. Inspect the modified files, especially if you are updating to a new checklist version and made some tweaks in the past.

Commit the changes.

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.

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.

Run x <- checklist::check_package(). This should run without returning an error.

Online setup on GitHub

Go to https://about.codecov.io and login with your GitHub account. Search for your package repository in the INBO organisation. Copy the token.

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.

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).

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)

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 check package on GitHub Actions

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@main
        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@main
        with:
          aptget: libudunits2-dev libpoppler-cpp-dev
```

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