Title: | A Thorough and Strict Set of Checks for R Packages and Source Code |
---|---|
Description: | An opinionated set of rules for R packages and R source code projects. |
Authors: | Thierry Onkelinx [aut, cre] (<https://orcid.org/0000-0001-8804-4216>, Research Institute for Nature and Forest (INBO)), Els Lommelen [ctb] (<https://orcid.org/0000-0002-3481-5684>, Research Institute for Nature and Forest (INBO)), Hans Van Calster [ctb] (<https://orcid.org/0000-0001-8595-8426>, Research Institute for Nature and Forest (INBO)), Research Institute for Nature and Forest (INBO) [cph, fnd] |
Maintainer: | Thierry Onkelinx <[email protected]> |
License: | GPL-3 |
Version: | 0.4.0 |
Built: | 2024-10-17 05:33:11 UTC |
Source: | https://github.com/inbo/checklist |
doi
: add a DOI badge
url
: add a website badge
add_badges(x = ".", ...)
add_badges(x = ".", ...)
x |
Either a |
... |
Additional arguments |
Other both:
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
## Not run: add_badges(url = "https://www.inbo.be") add_badges(doi = "10.5281/zenodo.8063503") add_badges(check_project = "inbo/checklist") add_badges(check_package = "inbo/checklist") add_badges(url = "https://www.inbo.be", doi = "10.5281/zenodo.8063503") ## End(Not run)
## Not run: add_badges(url = "https://www.inbo.be") add_badges(doi = "10.5281/zenodo.8063503") add_badges(check_project = "inbo/checklist") add_badges(check_package = "inbo/checklist") add_badges(url = "https://www.inbo.be", doi = "10.5281/zenodo.8063503") ## End(Not run)
Function to ask a simple yes no question
ask_yes_no(msg, default = TRUE, prompts = c("Yes", "No", "Cancel"), ...)
ask_yes_no(msg, default = TRUE, prompts = c("Yes", "No", "Cancel"), ...)
msg |
The prompt message for the user. |
default |
The default response. |
prompts |
Any of: a character vector containing 3 prompts corresponding to
return values of |
... |
Additional parameters, ignored by the default function. |
Other utils:
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
bookdown
and upload to ZenodoFirst clears all the existing files in the output_dir
set in
_bookdown_.yml
.
Then renders all required output formats and uploads them to Zenodo.
bookdown_zenodo()
creates a draft record when you don't specify a community
in the yaml.
Otherwise it creates a review request for the first community.
bookdown_zenodo( path, zip_format = c("bookdown::gitbook", "INBOmd::gitbook"), single_format = c("bookdown::pdf_book", "bookdown::epub_book", "INBOmd::pdf_report", "INBOmd::epub_book"), token, sandbox = TRUE, logger = "INFO" )
bookdown_zenodo( path, zip_format = c("bookdown::gitbook", "INBOmd::gitbook"), single_format = c("bookdown::pdf_book", "bookdown::epub_book", "INBOmd::pdf_report", "INBOmd::epub_book"), token, sandbox = TRUE, logger = "INFO" )
path |
The root folder of the report |
zip_format |
A vector with output formats that generate multiple files. The function will bundle all the files in a zip file for every format. |
single_format |
A vector with output formats that generate a single output file. The output will remain as is. |
token |
the user token for Zenodo.
By default an attempt will be made to retrieve token using |
sandbox |
When |
logger |
Type of logger for Zenodo upload.
Defaults to |
Other utils:
ask_yes_no()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
Setting the locale before sorting ensures a stable sorting order
c_sort(x, ...)
c_sort(x, ...)
x |
for |
... |
arguments to be passed to or from methods or (for the
default methods and objects without a class) to |
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
Use the checks from codemetar::give_opinions()
.
check_codemeta(x = ".")
check_codemeta(x = ".")
x |
Either a |
A checklist
object.
Other package:
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
CRAN imposes an impressive list of tests on every package before publication.
This suite of test is available in every R installation.
Hence we use this full suite of tests too.
Notice that check_package()
runs several additional tests.
check_cran(x = ".", quiet = FALSE)
check_cran(x = ".", quiet = FALSE)
x |
Either a |
quiet |
Whether to print check output during checking. |
A checklist
object.
Other package:
check_codemeta()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
DESCRIPTION
fileThe DESCRIPTION
file contains the most important meta-data of the package.
A good DESCRIPTION
is tidy, has a meaningful version number, full
author details and a clear license.
check_description(x = ".")
check_description(x = ".")
x |
Either a |
This function ensures the DESCRIPTION
is tidy, using tidy_desc()
.
The version number of the package must have either a 0.0
or a 0.0.0
format (see this discussion why
we allow only these formats).
The version number in every branch must be larger than the current version
number in the main or master branch.
New commits in the main or master must have a larger version number than the
previous commit.
We recommend to protect the main or master branch and to not commit into the
main or master.
Furthermore we check the author information.
Is INBO listed as copyright holder and funder?
Has every author an ORCID?
We check the license through check_license()
.
Other package:
check_codemeta()
,
check_cran()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
The function make sure that the documentation is up to date. Rules:
You must use roxygen2
to document the
functions.
If you use a README.Rmd
, it should be rendered.
You need at least a README.md
.
Don't use a NEWS.Rmd
but a NEWS.md
.
NEWS.md
must contain an entry for the current package version.
check_documentation(x = ".", quiet = FALSE)
check_documentation(x = ".", quiet = FALSE)
x |
Either a |
quiet |
Whether to print check output during checking. |
The function generates the help files from the roxygen2
tag in the R code.
Then it checks whether any of the help files changed.
We use the same principle with the README.Rmd
.
If any file changed, the documentation does not match the code.
Hence check_documentation()
returns an error.
A side effect of running check_documentation()
locally, is that it
generates all the documentation.
So the only thing left for you to do, is to commit these changes.
Pro tip: make sure RStudio renders the roxygen2
tags whenever you install
and restart the package.
We describe this in vignette("getting_started")
under "Prepare local
setup".
NEWS.md
# package_name version * Description of something that changed. * Lines should not exceed 80 characters. Start a new line with two space to continue an item. * Add a single blank line before and after each header. ## Second level heading * You can use second level headings when you want to add more structure. # `package_name` version * Adding back ticks around the package name is allowed.
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
Some actions will fail when these environment variables are not set. This function does only work on GitHub.
check_environment(x = ".")
check_environment(x = ".")
x |
Either a |
An invisible checklist
object.
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
A consistent naming schema avoids problems when working together,
especially when working with different OS.
Some OS (e.g. Windows) are case-insensitive whereas others (e.g. Linux) are
case-sensitive.
Note that the checklist
GitHub Actions will test your code on Linux,
Windows and MacOS.
check_filename(x = ".")
check_filename(x = ".")
x |
Either a |
The sections below describe the default rules.
We allow several exceptions when the community standard is different.
E.g. a package stores the function scripts in the R
folder, while our
standard enforces lower case folder names.
Use the community standard, even if it does not conform with the checklist
rules.
Most likely checklist
will have an exception for the name.
If not, you can file an issue and
motivate why you think we should add an exception.
Folder names should only contain lower case letters, numbers, dashes (-
)
and underscores (_
).
They can start with a single dot (.
).
Base names should only contain lower case letters, numbers, dashes (-
)
and underscores (_
).
File extensions should only contain lower case letters and numbers.
Exceptions: file extensions related to R
must have an upper case R
(
.R
, .Rd
, .Rda
, .Rnw
, .Rmd
, .Rproj
).
Exception to these exceptions: R/sysdata.rda
.
Underscores (_
) causes problems for graphical files when using LaTeX to
create pdf output.
This is how we generate pdf output from rmarkdown.
Therefore you need to use a dash (-
) as separator instead of
an underscores (_
).
Applies to files with extensions eps
, jpg
, jpeg
, pdf
, png
, ps
, svg
and .cls
.
We ignore files with .otf
or .ttf
extensions.
These are fonts files which often require their own file name scheme.
Other both:
add_badges()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
For the time being, this function only checks projects.
Keep in mind that R packages have requirements for the folder structure.
That is one of things that check_cran()
checks.
check_folder(x = ".")
check_folder(x = ".")
x |
Either a |
source
: contains all R
scripts and Rmd
files.
data
: contains all data files.
source
A simple project with only R
scripts or only Rmd
files can place all the
files directly in the source
folder.
More elaborate projects should place in the files in several folders under
source
.
Place every bookdown
document in a dedicated folder.
And create an RStudio project for that folder.
data
Simple projects in which source
has no subfolders, place data
at the
root of the project.
For more elaborate project you must choose between either data
at the root
of the project or data
as subfolder of the subfolders of source
.
E.g. source/report/data
.
Place the data in an open file format.
E.g. csv
, txt
or tsv
for tabular data.
We strongly recommend to use git2rdata::write_vc()
to store such data.
Use the geopackage
format for spatial data.
Optionally add description of the data as markdown files.
Other project:
check_project()
,
check_source()
Every package needs a clear license.
Without a license, the end-users have no clue under what conditions they can
use the package.
You must specify the license in the DESCRIPTION
and provide a LICENSE.md
file.
check_license(x = ".")
check_license(x = ".")
x |
Either a |
This functions checks if the DESCRIPTION
mentions one of the standard
licenses.
The LICENSE.md
must match this license.
Use setup_package()
to add the correct LICENSE.md
to the package.
Currently, following licenses are allowed:
GPL-3
MIT
We will consider pull requests adding support for other open source licenses.
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
This functions does static code analysis.
It relies on lintr::lint_package()
.
We recommend that you activate all code diagnostics in RStudio to help
meeting the requirements.
You can find this in the menu Tools > Global options > Code >
Diagnostics.
Please have a look at vignette("philosophy")
for more details on the rules.
check_lintr(x = ".", quiet = FALSE)
check_lintr(x = ".", quiet = FALSE)
x |
Either a |
quiet |
Whether to print check output during checking. |
Other both:
add_badges()
,
check_filename()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
A convenience function that runs all packages related tests in sequence.
The details section lists the relevant functions.
After fixing a problem, you can quickly check if it is solved by running only
the related check.
But we still recommend to run check_package()
before you push to GitHub.
And only push when the functions indicate that there are no problems.
This catches most problems before sending the code to GitHub.
check_package( x = ".", fail = !interactive(), pkgdown = interactive(), quiet = FALSE )
check_package( x = ".", fail = !interactive(), pkgdown = interactive(), quiet = FALSE )
x |
Either a |
fail |
Should the function return an error in case of a problem?
Defaults to |
pkgdown |
Test pkgdown website.
Defaults to |
quiet |
Whether to print check output during checking. |
List of checks in order:
check_cran()
check_lintr()
check_filename()
check_description()
check_documentation()
check_codemeta()
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
Set or update the required checks via setup_project()
.
check_project(x = ".", fail = !interactive(), quiet = FALSE)
check_project(x = ".", fail = !interactive(), quiet = FALSE)
x |
Either a |
fail |
Should the function return an error in case of a problem?
Defaults to |
quiet |
Whether to print check output during checking. |
Other project:
check_folder()
,
check_source()
A convenience function that runs test on a project with only .R
and .Rmd
files.
The details section lists the relevant functions.
When you fixed a problem, you can speed things up by running only the related
check.
We still recommend to run check_source()
before you push to GitHub.
And only push when the functions indicate that there are no problems.
This catches most problems before sending the code to GitHub.
check_source(x = ".", fail = !interactive())
check_source(x = ".", fail = !interactive())
x |
Either a |
fail |
Should the function return an error in case of a problem?
Defaults to |
List of checks in order:
check_lintr()
check_filename()
Other project:
check_folder()
,
check_project()
This function checks by default any markdown (.md
) or Rmarkdown (.Rmd
)
file found within the project.
It also checks any R help file (.Rd
) in the man
folder.
Use the set_exceptions()
method of the checklist
object to exclude files
or use a different language.
Have a look at vignette("spelling", package = "checklist")
for more
details.
check_spelling(x = ".", quiet = FALSE)
check_spelling(x = ".", quiet = FALSE)
x |
Either a |
quiet |
Whether to print check output during checking. |
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
A class which contains all checklist results.
checklist::spelling
-> checklist
package
A logical indicating whether the source code refers to a package.
get_checked
A vector with checked topics.
get_path
The path to the package.
get_required
A vector with the names of the required checks.
get_spelling
Return the issues found by check_spelling()
fail
A logical indicating if any required check fails.
template
A list for a check list template.
add_error()
Add errors
checklist$add_error(errors, item, keep = TRUE)
errors
A vector with errors.
item
The item on which to store the errors.
keep
Keep old results
add_linter()
Add results from lintr::lint_package()
checklist$add_linter(linter)
linter
A vector with linter errors.
add_motivation()
Add motivation for allowed issues.
checklist$add_motivation(which = c("warnings", "notes"))
which
Which kind of issue to add.
add_notes()
Add notes
checklist$add_notes(notes, item)
notes
A vector with notes.
item
The item on which to store the notes.
add_rcmdcheck()
Add results from rcmdcheck::rcmdcheck
checklist$add_rcmdcheck(errors, warnings, notes)
errors
A vector with errors.
warnings
A vector with warning messages.
notes
A vector with notes.
add_spelling()
Add results from check_spelling()
checklist$add_spelling(issues)
issues
A data.frame
with spell checking issues.
add_warnings()
Add warnings
checklist$add_warnings(warnings, item)
warnings
A vector with warnings.
item
The item on which to store the warnings.
allowed()
Add allowed warnings and notes
checklist$allowed( warnings = vector(mode = "list", length = 0), notes = vector(mode = "list", length = 0) )
warnings
A vector with allowed warning messages. Defaults to an empty list.
notes
A vector with allowed notes. Defaults to an empty list.
package
Does the check list refers to a package.
Defaults to TRUE
.
confirm_motivation()
Confirm the current motivation for allowed issues.
checklist$confirm_motivation(which = c("warnings", "notes"))
which
Which kind of issue to confirm.
new()
Initialize a new checklist
object.
checklist$new(x = ".", language, package = TRUE)
x
The path to the root of the project.
language
The default language for spell checking.
package
Is this a package or a project?
print()
Print the checklist
object.
Add quiet = TRUE
to suppress printing.
checklist$print(...)
...
See description.
set_required()
set required checks
checklist$set_required(checks = character(0))
checks
a vector of required checks
clone()
The objects of this class are cloneable with this method.
checklist$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other class:
citation_meta
,
organisation
,
spelling
citation_meta
R6 classA class which contains citation information.
get_errors
Return the errors
get_meta
Return the meta data as a list
get_notes
Return the notes
get_type
A string indicating the type of source.
get_path
The path to the project.
get_warnings
Return the warnings
new()
Initialize a new citation_meta
object.
citation_meta$new(path = ".")
path
The path to the root of the project.
print()
Print the citation_meta
object.
citation_meta$print(...)
...
currently ignored.
clone()
The objects of this class are cloneable with this method.
citation_meta$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other class:
checklist
,
organisation
,
spelling
update local branches that are behind their counterpart on origin.
list local branches that have diverged from their counterpart the origin.
list local branches without counterpart on origin that have diverged from the main branch.
remove local branches without counterpart on origin and fully merged into the main branch.
remove local copies of origin branches deleted at the origin.
clean_git(repo = ".", verbose = TRUE)
clean_git(repo = ".", verbose = TRUE)
repo |
The path to the git repository. If the directory is not a
repository, parent directories are considered (see git_find). To disable
this search, provide the filepath protected with |
verbose |
display some progress info while downloading |
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
This function makes a hexagonal logo in INBO style for the provided package name.
create_hexsticker( package_name, filename = path("man", "figures", "logo.svg"), icon, x = 0, y = 0, scale = 1 )
create_hexsticker( package_name, filename = path("man", "figures", "logo.svg"), icon, x = 0, y = 0, scale = 1 )
package_name |
package name that should be mentioned on the hexagonal sticker. |
filename |
filename to save the sticker. |
icon |
optional filename to an |
x |
number of pixels to move the icon to the right. Use negative numbers to move the icon to the left. |
y |
number of pixels to move the icon to the bottom. Use negative numbers to move the icon to the top. |
scale |
Scales the |
A figure is saved in the working directory or provided path.
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
## Not run: # make tempfile to save logo (or just use (path and) filename) #' output <- tempfile(pattern = "hexsticker", fileext = ".svg") create_hexsticker("checklist", filename = output) ## End(Not run)
## Not run: # make tempfile to save logo (or just use (path and) filename) #' output <- tempfile(pattern = "hexsticker", fileext = ".svg") create_hexsticker("checklist", filename = output) ## End(Not run)
Creates a package template in a new folder.
Use this function when you want to start a new package.
Please DO READ vignette("getting_started")
before running this function.
create_package( package, path = ".", title, description, keywords, language = "en-GB", license = c("GPL-3", "MIT"), communities = character(0), maintainer )
create_package( package, path = ".", title, description, keywords, language = "en-GB", license = c("GPL-3", "MIT"), communities = character(0), maintainer )
package |
Name of the new package. |
path |
Where to create the package directory. |
title |
A single sentence with the title of the package. |
description |
A single paragraph describing the package. |
keywords |
A vector of keywords. |
language |
Language of the project in |
license |
What type of license should be used? Choice between GPL-3 and MIT. Default GPL-3. |
communities |
An optional vector of Zenodo community id's. |
maintainer |
When missing, the function interactively lets you add the
maintainer and other authors.
Otherwise it must be the output of |
What you get with a checklist setup:
minimal folder structure and files required for an R package using INBO guidelines with GPL-3 or MIT license.
an RStudio project file
a local git repository
an initial NEWS.md
file
a template for an README.Rmd
set-up for automated checks and releases of the package using GitHub Actions.
a code of conduct and contributing guidelines.
the set-up for a pkgdown
website using the INBO corporate identity.
Other setup:
create_project()
,
prepare_ghpages()
,
set_license()
,
setup_package()
,
setup_project()
,
setup_source()
# maintainer in `utils::person()` format maintainer <- person( given = "Thierry", family = "Onkelinx", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0001-8804-4216") ) # creating the package path <- tempfile() dir.create(path) create_package( path = path, package = "packagename", title = "package title", description = "A short description.", maintainer = maintainer, language = "en-GB", license = "GPL-3", keywords = "keyword" )
# maintainer in `utils::person()` format maintainer <- person( given = "Thierry", family = "Onkelinx", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0001-8804-4216") ) # creating the package path <- tempfile() dir.create(path) create_package( path = path, package = "packagename", title = "package title", description = "A short description.", maintainer = maintainer, language = "en-GB", license = "GPL-3", keywords = "keyword" )
This function creates a new RStudio project with checklist
functionality.
create_project(path, project)
create_project(path, project)
path |
The folder in which to create the project as a folder. |
project |
The name of the project. |
Other setup:
create_package()
,
prepare_ghpages()
,
set_license()
,
setup_package()
,
setup_project()
,
setup_source()
Add words to custom dictionaries
custom_dictionary(issues)
custom_dictionary(issues)
issues |
The output of |
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
Store the default organisation rules.
First run org <- organisation$new()
with the appropriate argument.
Next you can store the configuration with default_organisation(org)
.
default_organisation(org = organisation$new())
default_organisation(org = organisation$new())
org |
An |
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
Cross-platform function to pass a command to the shell, using either
base::system()
or (Windows-only) base::shell()
, depending on the
operating system.
execshell(commandstring, intern = FALSE, path = ".", ...)
execshell(commandstring, intern = FALSE, path = ".", ...)
commandstring |
The system command to be invoked, as a string. Multiple commands can be combined in this single string, e.g. with a multiline string. |
intern |
a logical (not |
path |
The path from where the command string needs to be executed |
... |
Other arguments passed to |
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
The path arguments specifies the directory at which to start the search for a git repository. If it is not a git repository itself, then its parent directory is consulted, then the parent's parent, and so on.
is_repository(path = ".")
is_repository(path = ".")
path |
the location of the git repository, see details. |
TRUE if directory is in a git repository else FALSE
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
A clean working directory has no staged, unstaged or untracked files.
is_workdir_clean(repo)
is_workdir_clean(repo)
repo |
The path to the git repository. If the directory is not a
repository, parent directories are considered (see git_find). To disable
this search, provide the filepath protected with |
TRUE
when there are no staged, unstaged or untracked files.
Otherwise FALSE
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
This functions first runs clean_git()
.
Then it creates the new branch from the (updated) main branch.
new_branch(branch, verbose = TRUE, checkout = TRUE, repo = ".")
new_branch(branch, verbose = TRUE, checkout = TRUE, repo = ".")
branch |
name of branch to check out |
verbose |
display some progress info while downloading |
checkout |
move HEAD to the newly created branch |
repo |
The path to the git repository. If the directory is not a
repository, parent directories are considered (see git_find). To disable
this search, provide the filepath protected with |
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
Defunct functions
orcid2person()
orcid2person()
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
A class with the organisation defaults
as_person
The default organisation funder and rightsholder.
get_community
The default organisation Zenodo communities.
get_email
The default organisation email.
get_funder
The default funder.
get_github
The default GitHub organisation domain.
get_organisation
The organisation requirements.
get_rightsholder
The default rightsholder.
template
A list for a check list template.
new()
Initialize a new organisation
object.
organisation$new(...)
...
The organisation settings. See the details.
github
: the name of the github organisation.
Set to NA_character_
in case you don't want a mandatory github
organisation.
community
: the mandatory Zenodo community.
Defaults to "inbo"
.
Set to NA_character_
in case you don't want a mandatory community.
email
: the e-mail of the organisation.
Defaults to "[email protected]"
.
Set to NA_character_
in case you don't want an organisation e-mail.
funder
: the funder.
Defaults to "Research Institute for Nature and Forest (INBO)"
.
Set to NA_character_
in case you don't want to set a funder.
rightsholder
: the rightsholder.
Defaults to "Research Institute for Nature and Forest (INBO)"
.
Set to NA_character_
in case you don't want to set a rightsholder.
organisation
: a named list with one or more organisation default
rules.
The names of the element must match the e-mail domain name of the
organisation.
Every element should be a named list containing affiliation
and
orcid
.
affiliation
is a character vector with the approved organisation
names in one or more languages.
orcid = TRUE
indicated a mandatory ORCiD for every member.
Use an empty list in case you don't want to set this.
print()
Print the organisation
object.
organisation$print(...)
...
currently ignored.
clone()
The objects of this class are cloneable with this method.
organisation$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other class:
checklist
,
citation_meta
,
spelling
gh-pages
branch with a place holder pagePrepare a gh-pages
branch with a place holder page
prepare_ghpages(x = ".", verbose = TRUE)
prepare_ghpages(x = ".", verbose = TRUE)
x |
Either a |
verbose |
display some progress info while downloading |
Other setup:
create_package()
,
create_project()
,
set_license()
,
setup_package()
,
setup_project()
,
setup_source()
checklist_spelling
summaryDisplay a checklist_spelling
summary
## S3 method for class 'checklist_spelling' print(x, ...)
## S3 method for class 'checklist_spelling' print(x, ...)
x |
The |
... |
currently ignored |
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
read_checklist()
,
read_organisation()
,
write_checklist()
,
write_organisation()
The checklist package stores configuration information in the checklist.yml
file in the root of a project.
This function reads this configuration.
It is mainly used by the other functions inside the package.
If no checklist.yml
file is found at the path,
the function walks upwards through the directory structure until it finds
such file.
The function returns an error when it reaches the root of the disk without
finding a checklist.yml
file.
read_checklist(x = ".")
read_checklist(x = ".")
x |
Either a |
A checklist
object.
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_organisation()
,
write_checklist()
,
write_organisation()
The checklist package stores organisation information in the
organisation.yml
file in the root of a project.
read_organisation(x = ".")
read_organisation(x = ".")
x |
Either a |
An organisation
object.
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
write_checklist()
,
write_organisation()
Set the proper license
set_license(x = ".")
set_license(x = ".")
x |
Either a |
Other setup:
create_package()
,
create_project()
,
prepare_ghpages()
,
setup_package()
,
setup_project()
,
setup_source()
This function is a part of the GitHub Action.
Therefore it only works when run in a GitHub Action on the main or master
branch.
Otherwise it will only return a message.
It sets a new tag at the current commit using the related entry from
NEWS.md
as message.
This tag will turn into a release.
set_tag(x = ".")
set_tag(x = ".")
x |
Either a |
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
Use this function when you have an existing package and you want to use the
checklist functionality.
Please keep in mind that the checklist is an opinionated list of checks.
It might require some breaking changes in your package.
Please DO READ vignette("getting_started")
before running this function.
setup_package(path = ".", license = c("GPL-3", "MIT"))
setup_package(path = ".", license = c("GPL-3", "MIT"))
path |
The path to the package.
Defaults to |
license |
What type of license should be used? Choice between GPL-3 and MIT. Default GPL-3. |
What you get with a checklist setup:
minimal folder structure and files required for an R package using INBO guidelines with GPL-3 or MIT license.
an RStudio project file
a local git repository
an initial NEWS.md
file
a template for an README.Rmd
set-up for automated checks and releases of the package using GitHub Actions.
a code of conduct and contributing guidelines.
the set-up for a pkgdown
website using the INBO corporate identity.
Other setup:
create_package()
,
create_project()
,
prepare_ghpages()
,
set_license()
,
setup_project()
,
setup_source()
checklist
on an existing R projectUse this function to set-up or change the checklist
infrastructure for an
existing project.
The function interactively asks questions to set-up the required checks.
setup_project(path = ".")
setup_project(path = ".")
path |
the project root folder |
Other setup:
create_package()
,
create_project()
,
prepare_ghpages()
,
set_license()
,
setup_package()
,
setup_source()
This adds the required GitHub workflows to run check_source()
automatically
whenever you push commits to GitHub.
It also adds a
CC-BY 4.0 license file,
a
CODE_OF_CONDUCT.md
and the checklist configuration file (checklist.yml
).
setup_source(path = ".", language = "en-GB")
setup_source(path = ".", language = "en-GB")
path |
The path to the project.
Defaults to |
language |
Language of the project in |
Other setup:
create_package()
,
create_project()
,
prepare_ghpages()
,
set_license()
,
setup_package()
,
setup_project()
A class with the configuration for spell checking
default
The default language of the project.
get_md
The markdown files within the project.
get_r
The R files within the project.
get_rd
The Rd files within the project.
settings
A list with current spell checking settings.
new()
Initialize a new spelling
object.
spelling$new(language, base_path = ".")
language
the default language.
base_path
the base path of the project
print()
Print the spelling
object.
spelling$print(...)
...
currently ignored.
set_default()
Define which files to ignore or to spell check in a different language.
spelling$set_default(language)
language
The language.
set_exceptions()
Define which files to ignore or to spell check in a different language.
spelling$set_exceptions()
set_ignore()
Manually set the ignore vector. Only use this if you known what you are doing.
spelling$set_ignore(ignore)
ignore
The character vector with ignore file patterns.
set_other()
Manually set the other list. Only use this if you known what you are doing.
spelling$set_other(other)
other
a list with file patterns per additional language.
clone()
The objects of this class are cloneable with this method.
spelling$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other class:
checklist
,
citation_meta
,
organisation
Store author details for later usage
store_authors(x = ".")
store_authors(x = ".")
x |
Either a |
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
use_author()
,
validate_email()
,
validate_orcid()
,
yesno()
A tidy DESCRIPTION
uses a strict formatting and order of key-value pairs.
This function reads the current DESCRIPTION
and overwrites it with a tidy
version.
tidy_desc(x = ".")
tidy_desc(x = ".")
x |
Either a |
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
update_citation()
,
write_citation_cff()
,
write_zenodo_json()
The function extracts citation meta data from the project. Then it checks the required meta data. Upon success, it writes several files.
update_citation(x = ".", quiet = FALSE)
update_citation(x = ".", quiet = FALSE)
x |
Either a |
quiet |
Whether to print check output during checking. |
.zenodo.json
contains the citation information in the format that
Zenodo requires.
CITATION.cff
provides the citation information in the format that
GitHub requires.
inst/CITATION
provides the citation information in the format that
R packages require.
It is only relevant for packages.
An invisible checklist
object.
Source of the citation meta data:
package: DESCRIPTION
project: README.md
Should you want to add more information to the inst/CITATION
file,
add it to that file outside # begin checklist entry
and
# end checklist entry
.
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
write_citation_cff()
,
write_zenodo_json()
Reuse existing author information or add a new author. Allows to update existing author information.
use_author(email)
use_author(email)
email |
An optional email address. When given and it matches with a single person, the function immediately returns the information of that person. |
A data.frame with author information.
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
validate_email()
,
validate_orcid()
,
yesno()
It only checks the format of the text, not if the email address exists.
validate_email(email)
validate_email(email)
email |
A vector with email addresses. |
A logical vector.
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_orcid()
,
yesno()
Checks whether the ORCID has the proper format and the checksum.
validate_orcid(orcid)
validate_orcid(orcid)
orcid |
A vector of ORCID |
A logical vector with the same length as the input vector.
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
yesno()
checklist stores it configuration as a checklist.yml
file.
create_package()
, setup_package()
and setup_source()
generate a default
file.
If you need to allow some warnings or notes, you need to update the
configuration.
write_checklist(x = ".")
write_checklist(x = ".")
x |
Either a |
First run x <- checklist::check_package()
or
x <- checklist::check_source()
.
These commands run the checks and store the checklist
object in the
variable x
.
Next you can store the configuration with checklist::write_checklist(x)
.
This will first list any existing allowed warnings or notes.
For every one of them, choose whether you want to keep it or not.
Next, the function presents every new warning or note which you may allow or
not.
If you choose to allow a warning or note, you must provide a motivation.
Please provide a sensible motivation.
Keep in mind that checklist.yml
stores these motivations in plain text,
so they are visible for other users.
We use the yesno()
function to make sure you carefully read the questions.
When you allow a warning or note, this warning or note must appear.
Otherwise you get a "missing warning" or "missing note" error.
So if you fix an allowed warning or note, you need to rerun
checklist::write_checklist(x)
and remove the old version.
If you can solve a warning or note, then solve it rather than to allow it.
Only allow a warning or note in case of a generic "problem" that you can't
solve.
The best example is the checking CRAN incoming feasibility ... NOTE New submission
which appears when checking a package not on
CRAN.
That is should an allowed note as long as the package is not on CRAN.
Or permanently when your package is not intended for CRAN.
Do not allow a warning or note to fix an issue specific to your machine. That will result in an error when checking the package on an other machine (e.g. GitHub actions).
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_organisation()
CITATION.cff
fileThis file format contains the citation information.
It is supported by GitHub, Zenodo and Zotero.
This function is super-seeded by update_citation()
.
write_citation_cff(x = ".", roles)
write_citation_cff(x = ".", roles)
x |
Either a |
roles |
No longer used. |
An invisible checklist
object.
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_zenodo_json()
Store the organisation rules into organisation.yml
file.
First run org <- organisation$new()
with the appropriate argument.
Next you can store the configuration with write_organisation(org)
.
write_organisation(org, x = ".")
write_organisation(org, x = ".")
org |
An |
x |
Either a |
Other both:
add_badges()
,
check_filename()
,
check_lintr()
,
check_spelling()
,
custom_dictionary()
,
default_organisation()
,
print.checklist_spelling()
,
read_checklist()
,
read_organisation()
,
write_checklist()
.zenodo.json
fileZenodo uses the .zenodo.json
file to define the citation information.
See the Zenodo developers website
for more information.
write_zenodo_json(x = ".")
write_zenodo_json(x = ".")
x |
Either a |
An invisible checklist
object.
Other package:
check_codemeta()
,
check_cran()
,
check_description()
,
check_documentation()
,
check_environment()
,
check_license()
,
check_package()
,
set_tag()
,
tidy_desc()
,
update_citation()
,
write_citation_cff()
A function that asks a yes or no question to the user
yesno(...)
yesno(...)
... |
Currently ignored |
A logical where TRUE
implies a "yes" answer from the user.
Hadley Wickham [email protected]
Largely based on devtools:::yesno()
.
The user gets three options in an random order: 2 for "no", 1 for "yes".
The wording for "yes" and "no" is random as well.
This forces the user to carefully read the question.
Other utils:
ask_yes_no()
,
bookdown_zenodo()
,
c_sort()
,
clean_git()
,
create_hexsticker()
,
execshell()
,
is_repository()
,
is_workdir_clean()
,
menu_first()
,
new_branch()
,
orcid2person()
,
store_authors()
,
use_author()
,
validate_email()
,
validate_orcid()