---
title: "Setting up checklist for a package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Setting up checklist for a package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

Where do you want to set-up `checklist`?

1. I want to create a [new R package](#create-package) from scratch.
1. I want to use or update `checklist` in an [existing R package](#setup-package).

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

## Starting an R package from scratch {#create-package}

### Prepare online setup

1. Go to [https://github.com](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")`.
1. 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.
1. Open the newly created RStudio project.
1. 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).
1. Open the `README.Rmd` file and update the content.
  Knit the file and stage the `README.Rmd` and `README.md` files.
1. Review and commit the changes into an initial commit.
1. Add at least one function to the package.
1. [_Build_](https://r-pkgs.org/whole-game.html#install) the package.
1. 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_.
1. Run `checklist::write_checklist(x)`.
  This functions can convert some 'new' warnings and notes into 'allowed' warnings and notes.
1. 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.
1. Commit any remaining changes.
1. 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.
1. 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.
1. 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_.
1. Wait for all tests to finish (either green thick or red cross).
1. 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)`

1. 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 {#setup-package}

### Prerequisites

1. Make sure the package is using [git](https://inbo.github.io/tutorials/tutorials/git_introduction/) as version control system.
1. The git status must be clean.
You'll need to commit all changes first.
It is OK to have Untracked files.
1. 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")`.
1. 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.
1. Commit the changes.
1. 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.
1. 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.
1. 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.
1. 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_.
1. 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).
1. 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)`
1. 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`.