Package 'releaser'

Change the Remotes field in DESCRIPTION

Description

Update the Remotes field of a package DESCRIPTION file so that dependencies point to specific development targets (develop, snapshot, or main).

Usage

change_remotes_field(
  path,
  target = c("develop", "snapshot", "main"),
  verbose = TRUE
)

Arguments

path	[character] Path to the package root directory (or to the DESCRIPTION / NEWS.md file).
target	[character] Remote reference to write after the @ separator: "develop" (branch develop), "snapshot" (branch snapshot) or "main" (release tracking, written as ⁠*release⁠ in the Remotes field).
verbose	[logical] Whether to print additional information (default: TRUE).

Value

Invisibly returns the new vector of remote specifications (character).

Examples

path_rjd3workspace <- file.path(tempdir(), "rjd3workspace")
file.copy(
    from = system.file("rjd3workspace", package = "releaser"),
    to = dirname(path_rjd3workspace),
    recursive = TRUE
)

change_remotes_field(path = path_rjd3workspace, target = "develop")

---

Check for missing or deprecated documentation tag

Description

check_missing_examples_tag() Identifies exported functions that do not declare any ⁠@examples⁠ (or ⁠@examplesIf⁠) tag in their roxygen2 documentation. check_missing_examples_content() detects exported functions that declare an ⁠@examples⁠ tag but whose examples are not actually present in the combined example blocks. check_missing_title() identifies exported functions that do not define a ⁠@title⁠ tag in their documentation. check_describeIn_usage() lists all documented topics using the ⁠@describeIn⁠ tag. check_return_tag_usage() identifies functions still using ⁠@return⁠. check_missing_returns() identifies exported functions that declare neither a ⁠@returns⁠ nor a (deprecated) ⁠@return⁠ tag. Functions still using ⁠@return⁠ are reported by check_return_tag_usage() instead.

Usage

check_missing_examples_tag(x)

## S3 method for class 'character'
check_missing_examples_tag(x)

## S3 method for class 'docblock'
check_missing_examples_tag(x)

check_missing_examples_content(x)

## S3 method for class 'character'
check_missing_examples_content(x)

## S3 method for class 'docblock'
check_missing_examples_content(x)

check_missing_title(x)

## S3 method for class 'character'
check_missing_title(x)

## S3 method for class 'docblock'
check_missing_title(x)

check_describeIn_usage(x)

## S3 method for class 'character'
check_describeIn_usage(x)

## S3 method for class 'docblock'
check_describeIn_usage(x)

check_return_tag_usage(x)

## S3 method for class 'character'
check_return_tag_usage(x)

## S3 method for class 'docblock'
check_return_tag_usage(x)

check_missing_returns(x)

## S3 method for class 'character'
check_missing_returns(x)

## S3 method for class 'docblock'
check_missing_returns(x)

Arguments

x	Path to the R package or a docblock object.

Details

The ⁠@describeIn⁠ tag is generally discouraged in modern roxygen2 workflows. The ⁠@return⁠ tag is superseded by ⁠@returns⁠.

Value

A character vector of function names

Examples

my_pkg_dir <- "path/to/my/package"

# Single checks
check_missing_returns(my_pkg_dir)
check_return_tag_usage(my_pkg_dir)
check_describeIn_usage(my_pkg_dir)
check_missing_examples_tag(my_pkg_dir)
check_missing_examples_content(my_pkg_dir)
check_missing_title(my_pkg_dir)

---

Check R package documentation

Description

Performs a series of documentation consistency checks on a package using roxygen2 parsed blocks.

The following checks are performed:

• Missing ⁠@examples⁠ tag in exported functions

• Missing example content

• Missing ⁠@title⁠

• Usage of discouraged ⁠@describeIn⁠

• Usage of deprecated ⁠@return⁠

• Missing ⁠@returns⁠

Usage

check_docs(pkg_dir = ".", verbose = TRUE, error_on_fail = FALSE)

Arguments

pkg_dir	Path to the R package.
verbose	Logical. Whether to print a formatted summary (default: TRUE).
error_on_fail	Logical. If TRUE, stops execution if any issue is found.

Value

An object of class "releaser_doc_check" containing a named list of detected issues.

Examples

my_pkg_dir <- "path/to/my/package"

# Full check
results <- check_docs(my_pkg_dir)

---

Compute possible future semantic versions

Description

Given a current package version, compute the potential next patch, minor, and major versions following semantic versioning rules.

Usage

get_different_future_version(version_number, verbose = TRUE)

Arguments

version_number	[character] Current version number string (e.g. "1.2.3").
verbose	[logical] Whether to print additional information (default: TRUE).

Value

A named character vector with:

• current_version – the input version,

• future_patch_version – next patch version,

• future_minor_version – next minor version,

• future_major_version – next major version.

Examples

get_different_future_version("1.2.3")

---

List GitHub repository branches

Description

Retrieve all branch names from a GitHub repository.

Usage

get_github_branches(gh_repo = file.path("r-lib", "usethis"), verbose = TRUE)

Arguments

gh_repo	[character] GitHub repository in the format "owner/repo".
verbose	[logical] Whether to print additional information (default: TRUE).

Value

A character vector with branch names.

Examples

get_github_branches("r-lib/usethis")

---

Get latest GitHub release version

Description

Retrieve the version number of the latest GitHub release for a repository and optionally print versions found across all branches. When the repository has no release, the version of the default branch is returned instead.

Usage

get_latest_version(
  gh_repo = file.path("r-lib", "usethis"),
  max_branches = 50L,
  verbose = TRUE
)

Arguments

gh_repo	[character] GitHub repository in the format "owner/repo".
max_branches	[integer] Maximum number of branches to inspect, to limit the number of GitHub API calls (default: 50L).
verbose	[logical] Whether to print additional information (default: TRUE).

Value

A character string with the version of the latest release, or of the default branch when the repository has no release.

Examples

get_latest_version("r-lib/usethis")

---

Display result of documentation check

Description

Display result of documentation check

Usage

## S3 method for class 'releaser_doc_check'
print(x, ...)

Arguments

x	releaser_doc_check object
...	Not used argument.

Value

invisibly the object x

Examples

my_pkg_dir <- "path/to/my/package"

# Full check
results <- check_docs(my_pkg_dir)

---

Deprecated functions

Description

update_news_md modify the NEWS.md file of a package to replace the "Unreleased" section with a new version heading and update GitHub comparison links. get_changes extracts the section of NEWS.md corresponding to a given version.

Usage

update_news_md(path, version_number, verbose = TRUE)

get_changes(path, version_number, verbose = TRUE)

Arguments

path	[character] Path to the package root directory (or to the DESCRIPTION / NEWS.md file).
version_number	[character] Current version number string (e.g. "1.2.3").
verbose	[logical] Whether to print additional information (default: TRUE).

Details

The argument version_number is the new version number to update the changelog.

Value

update_news_md invisibly returns TRUE if the file was successfully updated. get_changes returns a character string containing the formatted changelog for the given version.

Examples

path_rjd3workspace <- file.path(tempdir(), "rjd3workspace")
file.copy(
    from = system.file("rjd3workspace", package = "releaser"),
    to = dirname(path_rjd3workspace),
    recursive = TRUE
)

update_news_md(path = path_rjd3workspace, version_number = "1.2.3")


path_rjd3workspace <- system.file("rjd3workspace", package = "releaser")

get_changes(path = path_rjd3workspace, version_number = "Unreleased")
get_changes(path = path_rjd3workspace, version_number = "3.2.4")
get_changes(path = path_rjd3workspace, version_number = "3.5.1")

---

Set latest versions for GitHub dependencies

Description

Update the DESCRIPTION file of a package so that all dependencies whose name starts with rjd3 require the latest released version from the rjdverse.

Usage

set_latest_rjdverse_version(path, verbose = TRUE)

Arguments

path	[character] Path to the package root directory (or to the DESCRIPTION / NEWS.md file).
verbose	[logical] Whether to print additional information (default: TRUE).

Value

Used for its side effect on the DESCRIPTION file (no return value).

Examples

path_rjd3workspace <- file.path(tempdir(), "rjd3workspace")
file.copy(
    from = system.file("rjd3workspace", package = "releaser"),
    to = dirname(path_rjd3workspace),
    recursive = TRUE
)

set_latest_rjdverse_version(path = path_rjd3workspace)

---

Set organization remotes in the Remotes field

Description

Add GitHub remotes to the Remotes field of the DESCRIPTION file for the dependencies of a given GitHub organization.

Usage

set_rjdverse_remotes(path, verbose = TRUE)

Arguments

path	Path to the root of the package.
verbose	Logical. Should informative messages be displayed?

Details

All dependencies whose package name starts with rjd3 (rjdverse packages by default) are added to the Remotes field as GitHub remotes of rjdverse.

Value

Invisibly the current content of the Remotes field.

Examples

path_rjd3workspace <- file.path(tempdir(), "rjd3workspace")
file.copy(
    from = system.file("rjd3workspace", package = "releaser"),
    to = dirname(path_rjd3workspace),
    recursive = TRUE
)

set_rjdverse_remotes(path = path_rjd3workspace)

---