epiverse-trace / packagetemplate Goto Github PK

https://lorenzwalthert.github.io/touchstone/

Examples in EpiNow2 and epinowcast

Since this repo is a template, I'm not sure if it should be expected that the DESCRIPTION file reflects the actual contributions to the repo.

From a practical point of view, I would find it very convenient to have the details (including ORCID) of all epiverse-trace members since it's usually much easier to selectively remove people than to have to find their ORCID, maybe double check how their name is spelled, etc. whenever you want to create a new package.

ORCID and RECON came up during spell check. I think they are fairly common and we should consider adding them to the WORDLIST file.

The current README structure is a bit awkward because it mixes a template for the README, as well as instructions on how to use this template & how to create a new R package from the command line.

It would be clearer if the README just included a skeleton of the information we want to include in the READMEs of all Epiverse-TRACE packages. I'd recommend we move the "meta" instructions to the Wiki of this repo.

@pratikunterwegs, since you created the command-line instructions, how would you feel about moving them to the wiki?

Please copy the following checklist in an issue in the package you're cleaning:

## Supercharge your pkgdown website

- [ ] Verify that website URL is listed in `_pkgdown.yml`
- [ ] Verify pkgdown site is using epiversetheme
- [ ] Add logo to `epiverse-trace/hex-stickers`
- [ ] Use svg version of logo
- [ ] Verify logo is properly detected by pkgdown & r-universe (path and name need to be exactly `man/figures/logo.png` or `man/figures/logo.svg`)
- [ ] Add a pkgdown reference index: https://pkgdown.r-lib.org/reference/build_reference.html#reference-index.
      Use selectors (e.g., `starts_with()` or `contains()`) to select functions rather than an explicit list. This serves the double purpose of checking that functions follow a coherent naming scheme.
- [ ] Verify intro vignette appears under 'Get started'
- [ ] Verify vignettes are ordered correctly (if applicable)
- [ ] Verify all images include helpful alt-text

## Developer tools

- [ ] Update lintr, roxygen, usethis, testthat, devtools to the latest version on your local computer: `pak::pak(c("lintr", "devtools"), dependencies = TRUE)`
- Copy from packagetemplate:
  - [ ] [`.lintr`](https://github.com/epiverse-trace/packagetemplate/blob/main/.lintr) config file
  - [ ] [GitHub Actions worfklows](https://github.com/epiverse-trace/packagetemplate/tree/main/.github/workflows)
  - [ ] [`tools/`](https://github.com/epiverse-trace/packagetemplate/tree/main/tools) folder
  - [ ] [`tests/spelling.R`](https://github.com/epiverse-trace/packagetemplate/blob/main/tests/spelling.R)
  - [ ] [`tests/testthat/helper-state.R`](https://github.com/epiverse-trace/packagetemplate/blob/main/tests/testthat/helper-state.R)
  - [ ] [`tests/testthat/setup-options.R`](https://github.com/epiverse-trace/packagetemplate/blob/main/tests/testthat/setup-options.R)
- [ ] Run `spelling::spell_check_package()`

## Misc good practice

- [ ] Change files ending in `.r` to `.R` in `R/` and/or `tests/testthat/`"
- [ ] Review usage of `# nolint` comments. New versions of lintr may have squashed previous bugs
- [ ] Update year in license file

## Documentation

- [ ] Use roxygen2 markdown syntax (`usethis::use_roxygen_md()`)
- [ ] Add a related project section at the end of the `README`
- [ ] Check that all URLs are working, up-to-date, and leading directly to the expected page: `urlchecker::url_check()`
- [ ] Add package-level documentation page: `usethis::use_package_doc()`
- [ ] Move package-level imports to the package-level documentation
- [ ] Verify that all `@import` and `@importFrom` import functions that are actually used in the relevant function
- [ ] Identify potential for [reuse in documentation](https://roxygen2.r-lib.org/articles/reuse.html)
- [ ] Run `devtools::document()`

## `DESCRIPTION`

- [ ] Verify if any package in `Remotes` is still necessary
- [ ] Check that [package `Description`](https://github.com/epiverse-trace/packagetemplate/blob/59bbe3cafb1adf479b6e8d295e73c73ddca1d5d2/DESCRIPTION#L18-L20) is still in line with the current scope
- [ ] Make sure links to GitHub repository and issue tracker are listed: `usethis::use_github_links()`
- [ ] Re-order and standardize `DESCRIPTION` with `desc::desc_normalize()`
- [ ] Submit a PR adding yourself as author to packagetemplate

## Final `R CMD check`

- [ ] Run `devtools::check()` locally to catch `NOTE`s and `WARNING`s that can still easily slip through continuous integration

## GitHub

- [ ] Check if issues are still relevant. If not, please close them, ideally with a link to the commit fixing them or a comment explaining why they no longer apply.
- [ ] Check if [discussions](https://github.com/orgs/epiverse-trace/discussions) you started are still ongoing. If not, please close the thread.

This would allow us to more easily identify and isolate these issues, and possibly forward them to other communication channels, such as slack, for input of the wider group.
I'm currently thinking of naming this label "feedback".

Suggested by @zmcucunuba.

since the workflow only runs when README.Rmd is changed

I think this change
3e3a285
means the actions never get triggered (or at least that was the case when I had this line in the workflow)

This issue is to flag that {urlchecker} won't catch wrong URIs when cross-referencing vignettes, i.e., linking a vignette from another vignette using ...see [package vignette](package_vignette.html). Suggest adding a task to the spring cleaning list to catch bad URIs.

As mentioned by @TimTaylor on the internal slack workspace, and as discussed on the [R-pkg-devel] mailing list, we should be conscious of our resource usage when usage GitHub Actions. Especially, since we collectively agreed in our values that we aim at being environmentally conscious.

Here are couple of ideas:

• from @TimTaylor: only run R CMD check when a change to the package has been made. In particular, we don't expect changes to the README, _pkgdown.yml, other GHA workflow files, etc. to change the output of R CMD check
• use a fail-fast strategy for matrix workflow. For example, if R CMD check fails on macOS, we could immediately stop R CMD check on all other platforms since we have already noticed an error to fix and there's no need to confirm it on other platforms. A potential downside here is that it makes platform-specific errors more difficult to identify and to diagnose.
• stop workflows triggered by previous commits if a new commit has been pushed. The idea is that the result of R CMD check or lintr or older commits will lead to an outdated and useless result. This is already implemented in the pkgdown.yml workflow and could be replicated in other workflows.

Comments on these ideas and further suggestions are very welcome!

The package template is currently called "readepi". I think it would be better to have a more generic name like "template" or "packagetemplate".

Is your feature request related to a problem? Please describe.

The default community health files are located in the organization .github repo. These files propagate the accessibility to CoC and Contrib files across package repos. In other words:

• Inside github,
  • if the package repo does have a CoC/Contrib file, it will redirect to package repo CoC/Contrib file.
  • if not, it will redirect to the organization .github CoC/Contrib file

However, this propagation has no effect on the pkgdown websites. CoC's issue is solved by the epiversetheme, but this does not work for Contrib files. CoC can be the same across package repos, while Contrib files can turn into customized files.

• Inside a pkgdown website
  • if the package repo does have a Contrib file, it is shown in the package website
  • if not, it is not shown on the package website (and it should always be)
  • the epiversetheme does not solve this for Contrib files because the link is constrained by the one defined in the theme, and it does not change in the presence of a custom package repo Contrib file.
  • thus, the packagetemplate repo must have its own Contrib file as a template

Describe the solution you'd like

The CONTRIBUTING.md template file can mix the:

• first paragraph from episoap/CONTRIBUTING.md, and
• rest of paragraphs from .github/CONTRIBUTING.md

Benefits:

• it keeps a direct link reference to the epiverse-trace .github/CONTRIBUTING.md including Community Manager contact.
• the rest of the text can be used as a useful template as it is.

• isTRUE() / isFALSE() should not be used by default but only in very specific cases
• citEntry() is deprecated in favour of bibentry()

Once it has been thoroughly tested

The tutorial that @pratikunterwegs kindly wrote to set up the package template using the terminal is very useful but almost invisible and hard to find. Maybe, it might help to add a link in the README for visibility.

https://testthat.r-lib.org/reference/set_state_inspector.html

This could be useful to make sure we don't modify the global state in any of our functions. However, Hadley mentioned in r-lib/testthat#1816 that he doesn't imagine this being always enabled. I need to run some tests to see if it generates too many positives to be enabled by default.

https://testthat.r-lib.org/articles/parallel.html

This needs to be rollout carefully because it may cause issues in packages that have dependency within their tests.

https://github.com/GitHubSecurityLab/actions-permissions/tree/main/advisor

https://github.blog/2023-06-26-new-tool-to-secure-your-github-actions/

r-lib/lintr#1757

To keep the package repo root clean and consolidate everything related to CI in .github/

Now that merge queues are available, it might be worth considering adding a merge queue to the list of triggers for the template CI workflows.

Following the issue template to the T here, including the intial complaining :)

I have a dreadful aversion to using my mouse/trackpad, and only want to use the command line to:

1. Create a git repository
2. Create a Github repository
3. Create an R package skeleton
4. Set up tests for my R package
5. Set up a webpage to document my R package
6. Set up continuous integration using Github Actions for my package

Using this conversation on {bpmodels} about CITATION.cff files as inspiration, I would like ask that we:

• Consider adding CITATION.cff to our packages to ease the process of citing our packages,
• Add a GHA configuration to packagetemplate for prospective use to sync the three files listed in the title above.

The following article provides more context on the benefit of using .cff files.

Tagging @joshwlambert as he raised this.

Once r-lib/lintr#1100 has been released.

There will be a consultation with the team to verify this is not going to cause heavy disruption.

Technical benefits I see to explicit returns:

• can be linted (e.g., unreachable_code_linter())
• closer to other language, thus easier to read & understand for non-R users

It may be worth using the GitHub R gitignore

As new updates are applied to packagetemplate, the existing epiverse packages in development may retain outdated workflows or other package components. It would be good to think about whether there is a way to somehow automate the process of updates in packagetemplate triggering updates on the rest of the epiverse packages.

I'm not sure how this would be done, perhaps some sort of workflow that opens a pull request on the existing packages.

Before doing a release, maintainers should review the diff and verify that no contributor remained unacknowledged (whether in NEWS or DESCRIPTION depending on the case).

• Add CITATION.cff (#31)
• Upload to zenodo on releases via HERMES

Running spell check by default uses en-US and flags words spelt in en-GB. After adding Language: en-GB to DESCRIPTION these lines disappeared. See code snippet below

spelling::spell_check_package()
#> DESCRIPTION does not contain 'Language' field. Defaulting to 'en-US'.
#> ...
#> recoded       cleanepi.Rmd:106
#> standardise   calculate_age.Rd:15
#> Standardise   cleanepi.Rmd:104

Since the epiverse collaboration has British institutions involved. It would make life easier to add this field to {packagetemplate} to reduce the number of false spelling mistakes that will be raised by using en-US by default.

@epiverse-trace/lac

The workflow are currently configured with the idea of using just a main branch and some feature branches. If you use a develop branch, we should make sure that checks are triggered on this branch as well.

For this, we need to settle on a definitive need for this branch. I've seen dev, develop or development in other project, which one do you prefer to use?