This function creates a new R package structure according to the current
best practices.
Essential features of an R package are created (DESCRIPTION and
NAMESPACE files, and R/ and man/ folders). The project is also
versioned with git and a generic R .gitignore is added.
IMPORTANT - Before using this function user needs to create a new folder
(or a new project if using RStudio) and run this function inside this folder
(by using setwd() or by opening the Rproj in a new RStudio session).
The name of the package will be the same as the name of this folder.
Some rules must be respected:
https://r-pkgs.org/workflow101.html#name-your-package.
Some fields of the DESCRIPTION file (maintainer information, package name,
license, URLs, and roxygen2 version) are automatically filled but
others (like title and description) need to be edited manually.
Additional features are also created: a CITATION file, a README.Rmd, and
tests/ and vignettes/ folders (optional). See the vignette
Get started
for a complete overview of the full structure.
A GitHub repository can also be created (default) following the
"GitHub last" workflow
(https://happygitwithr.com/existing-github-last.html).
Configuration files for GitHub Actions to automatically 1) check the
package, 2) test and report code coverage, and 3) deploy the website using
pkgdown
will be added in the .github/ folder. See below the section
Creating a GitHub repo.
new_package(
license = "GPL (>= 2)",
status = "concept",
lifecycle = "experimental",
vignette = TRUE,
test = TRUE,
create_repo = TRUE,
private = FALSE,
gh_check = TRUE,
codecov = TRUE,
website = TRUE,
gh_render = TRUE,
given = NULL,
family = NULL,
email = NULL,
orcid = NULL,
organisation = NULL,
overwrite = FALSE,
quiet = FALSE
)A character vector of length 1. The license to be used for
this package. Run get_licenses() to choose an appropriate one.
Default is license = 'GPL (>= 2)'
The license can be changed later by calling add_license() (and
add_license_badge() or refresh() to update the corresponding badge in
the README).
A character vector of length 1. The status of the project
according to the standard defined by the https://www.repostatus.org
project. One among 'concept' (default), 'wip', 'suspended',
'abandoned', 'active', 'inactive', or 'unsupported'.
See add_repostatus_badge() for further information.
This argument is used to add a badge to the README.Rmd to help visitors
to better understand your project. If you don't want this badge use
status = NULL.
This status can be added/changed later by using add_repostatus_badge().
A character vector of length 1. The life cycle stage of the
project according to the standard defined at
https://lifecycle.r-lib.org/articles/stages.html. One among
'experimental' (default), 'stable', 'deprecated', or 'superseded'.
See add_lifecycle_badge() for further information.
This argument is used to add a badge to the README.Rmd to help visitors
to better understand your project. If you don't want this badge use
lifecycle = NULL.
This stage can be added/changed later by using add_lifecycle_badge().
A logical value. If TRUE (default) creates a vignette in
vignettes/. Packages knitr and
rmarkdown are also added to the
Suggests field in the DESCRIPTION file.
A logical value. If TRUE (default) initializes units tests by
running usethis::use_testthat(). Package
testthat is also added to the Suggests
field in the DESCRIPTION file.
A logical value. If TRUE (default) creates a repository
(public if private = FALSE or private if private = TRUE) on GitHub.
See below the section Creating a GitHub repo.
A logical value. If TRUE creates a private repository on
user GitHub account (or organisation). Default is private = FALSE.
A logical value. If TRUE (default) configures GitHub
Actions to automatically check and test the package after each push. This
will run R CMD check on the three major operating systems (Ubuntu, macOS,
and Windows) on the latest release of R. See add_github_actions_check()
for further information.
If create_repo = FALSE this argument is ignored.
A logical value. If TRUE (default) configures GitHub
Actions to automatically report the code coverage of units tests after
each push. See add_github_actions_codecov() for further information.
If create_repo = FALSE this argument is ignored.
A logical value. If TRUE (default) configures GitHub
Actions to automatically build and deploy the package website
(using pkgdown)
after each push. A gh-pages branch will be created using
usethis::use_github_pages() and the GitHub repository will be
automatically configured to deploy website.
If create_repo = FALSE this argument is ignored.
A logical value. If TRUE (default) configures GitHub
Actions to automatically knit the README.Rmd after each push.
See add_github_actions_render() for further information.
If create_repo = FALSE this argument is ignored.
A character vector of length 1. The given name of the
maintainer of the package. If NULL (default) the function will try to
get this value by reading the .Rprofile file.
For further information see set_credentials() and below the section
Managing credentials.
A character vector of length 1. The family name of the
maintainer of the package. If NULL (default) the function will try to
get this value by reading the .Rprofile file.
For further information see set_credentials() and below the section
Managing credentials.
A character vector of length 1. The email address of the
maintainer of the package. If NULL (default) the function will try to
get this value by reading the .Rprofile file.
For further information see set_credentials() and below the section
Managing credentials.
A character vector of length 1. The ORCID of the maintainer of
the package. If NULL (default) the function will try to get this value
by reading the .Rprofile file.
For further information see set_credentials() and below the section
Managing credentials.
A character vector of length 1. The GitHub organisation to host the repository. If defined it will overwrite the GitHub pseudo.
Default is organisation = NULL (the GitHub pseudo will be used).
A logical value. If TRUE files written from templates and
modified by user are erased. Default is overwrite = FALSE.
Be careful while using this argument.
A logical value. If TRUE messages are deleted. Default is
FALSE.
No return value.
The purpose of the package rcompendium is to make easier the creation of R
package/research compendium so that user can focus on the code/analysis
instead of wasting time organizing files.
The recommended workflow is:
Create an empty RStudio project;
Store your credentials with set_credentials() (if not already done);
Run new_package() to create a new package structure (and the GitHub
repository);
Edit some metadata in DESCRIPTION, CITATION, and README.Rmd;
Implement, document & test functions (the fun part);
Update the project (update .Rd files, NAMESPACE, external
dependencies in DESCRIPTION, re-knit README.Rmd, and check package
integrity) with refresh();
Repeat steps 5 and 6 while developing the package.
You can use the arguments given, family, email, and orcid
directly with the function new_package() (and others). But if you create
a lot a projects (packages and/or compendiums) it can be frustrating in the
long run.
An alternative is to use ONCE AND FOR ALL the function
set_credentials() to permanently store this information in the
.Rprofile file. If these arguments are set to NULL (default) each
function of the package rcompendium will search in this .Rprofile file.
It will save your time (it's the purpose of this package).
Even if you have stored your information in the .Rprofile file you will
always be able to modify them on-the-fly (i.e. by using arguments of the
new_package()) or permanently by re-running set_credentials().
First run gh::gh_whoami() to see if your git is correctly configured. If
so you should see something like:
{
"name": "John Doe",
"login": "jdoe",
"html_url": "https://github.com/jdoe",
...
}Otherwise you might need to run:
gert::git_config_global_set(name = "user.name",
value = "John Doe")
gert::git_config_global_set(name = "user.email",
value = "john.doe@domain.com")
gert::git_config_global_set(name = "github.user",
value = "jdoe")See gert::git_config_global_set() for further information.
To create the GitHub repository directly from R, the package rcompendium
uses the function usethis::use_github(), an client to the GitHub REST API.
The interaction with this API required an authentication method: a
GITHUB PAT (Personal Access Token).
If you don't have a GITHUB PAT locally stored, you must:
Obtain a new one from your GitHub account. Make sure to select at least the first two scopes (private repository and workflow)
Store it in the ~/.Renviron file by using usethis::edit_r_environ()
and adding the following line: GITHUB_PAT='ghp_99z9...z9'
Run usethis::gh_token_help() for more information about getting and
configuring a GITHUB PAT.
If everything is well configured you should see something like this after
calling gh::gh_whoami():
{
"name": "John Doe",
"login": "jdoe",
"html_url": "https://github.com/jdoe",
"scopes": "delete_repo, repo, workflow",
"token": "ghp_99z9...z9"
}And you will be able to create a GitHub repository directly from R!
Other setup functions:
new_compendium(),
refresh(),
set_credentials()
if (FALSE) {
library(rcompendium)
## Define **ONCE FOR ALL** your credentials ----
set_credentials(given = "John", family = "Doe",
email = "john.doe@domain.com",
orcid = "9999-9999-9999-9999", protocol = "ssh")
## Create an R package ----
new_package()
## Start developing functions ----
## ...
## Update package (documentation, dependencies, README, check) ----
refresh()
}