Package 'voucher'

Add a user to the vouched contributors list.

Description

This adds the user to the vouched list, removing any existing entry (vouched or denounced) for that user first.

Usage

add(username, write = FALSE, default_platform = "", vouched_file = "")

Arguments

username	Username to vouch for (supports platform:user format). Missing values (NA) are dropped with an informational message.
write	Write the file in-place (default: output to stdout).
default_platform	Assumed platform for entries without explicit platform.
vouched_file	Path to vouched contributors file (default: VOUCHED.td or .github/VOUCHED.td).

Value

Invisibly returns the updated trustdown text.

Attribution

Documentation for this function is copied nearly verbatim from vouch and is owned by Mitchell Hashimoto.

Examples

## Not run: 
# Preview new file contents (default)
add("someuser")

# Write the file in-place
add("someuser", write = TRUE)

# Add with platform prefix
add("github:someuser", write = TRUE)

## End(Not run)

---

Check a user's vouch status.

Description

This checks if a user is vouched, denounced, or unknown.

Usage

check(username, default_platform = "", vouched_file = "", blame = FALSE)

Arguments

username	Username to check (supports platform:user format). Missing values (NA) are dropped with an informational message.
default_platform	Assumed platform for entries without explicit platform.
vouched_file	Path to vouched contributors file (default: VOUCHED.td or .github/VOUCHED.td).
blame	Include git blame author for a matched entry when available.

Value

One of "vouched", "denounced", or "unknown".

Attribution

Documentation for this function is copied nearly verbatim from vouch and is owned by Mitchell Hashimoto.

Examples

## Not run: 
check("someuser")
check("github:someuser")

## End(Not run)

---

Denounce a user by adding them to the VOUCHED file with a minus prefix.

Description

This removes any existing entry for the user and adds them as denounced. An optional reason can be provided which will be added after the username.

Usage

denounce(
  username,
  write = FALSE,
  reason = "",
  default_platform = "",
  vouched_file = ""
)

Arguments

username	Username to denounce (supports platform:user format). Missing values (NA) are dropped with an informational message.
write	Write the file in-place (default: output to stdout).
reason	Optional reason for denouncement.
default_platform	Assumed platform for entries without explicit platform.
vouched_file	Path to vouched contributors file (default: VOUCHED.td or .github/VOUCHED.td).

Value

Invisibly returns the updated trustdown text.

Attribution

Documentation for this function is copied nearly verbatim from vouch and is owned by Mitchell Hashimoto.

Examples

## Not run: 
# Preview new file contents (default)
denounce("badactor")

# Denounce with a reason
denounce("badactor", reason = "Submitted AI slop")

# Write the file in-place
denounce("badactor", write = TRUE)

# Denounce with platform prefix
denounce("github:badactor", write = TRUE)

## End(Not run)

---

Initialize vouch in the current project

Description

Creates a starter VOUCHED.td file at .github/VOUCHED.td and ensures .github is ignored in package builds by adding ⁠^\\.github$⁠ to .Rbuildignore when needed.

Usage

use_vouch()

Details

If a vouch file already exists (VOUCHED.td or .github/VOUCHED.td), this function exits without making changes.

Value

Invisibly returns NULL.

Examples

## Not run: 
use_vouch()

## End(Not run)

---

Use vouch GitHub Actions

Description

Function to add some vouch workflows, like usethis::use_github_action(). Details about the actions can be found at https://github.com/mitchellh/vouch/tree/main/action; short summaries copied from there follow.

Usage

vouch_gha(
  action = c("check-issue", "check-pr", "manage-by-discussion", "manage-by-issue",
    "sync-codeowners")
)

Arguments

action

The GitHub Action template workflow to add.

Details

check-issue: Check if an issue author is a vouched contributor. Bots and collaborators with write access are automatically allowed. Denounced users are always blocked. When require-vouch is true (default), unvouched users are also blocked. Use auto-close to close issues from blocked users.

check-pr: Check if a PR author is a vouched contributor. Bots and collaborators with write access are automatically allowed. Denounced users are always blocked. When require-vouch is true (default), unvouched users are also blocked. Use auto-close to close PRs from blocked users.

manage-by-discussion: Manage contributor vouch status via discussion comments. When a collaborator with sufficient permissions comments vouch on a discussion, the discussion author is added to the vouched contributors list. When they comment denounce, the user is denounced. When they comment unvouch, the user is removed from the list entirely. The trigger keywords and required permission levels are configurable.

manage-by-issue: Manage contributor vouch status via issue comments. When a collaborator with sufficient permissions comments vouch on an issue, the issue author is added to the vouched contributors list. When they comment denounce, the user is denounced. When they comment unvouch, the user is removed from the list entirely. The trigger keywords and required permission levels are configurable.

sync-codeowners: Sync CODEOWNERS entries into the VOUCHED list. The action expands any team owners to their members and adds missing users to the vouch file.

Attribution

Documentation for this function is copied nearly verbatim from vouch and is owned by Mitchell Hashimoto.

---