update-r-news

Draft or update an R package NEWS file (NEWS.md, NEWS, or NEWS.Rd) from the git commit history since the last Bioconductor release. When commit messages are too vague to classify, the skill inspects the associated diff to infer what changed. All drafts are shown for review and confirmation before writing to disk.

This skill is designed for Bioconductor packages on the devel branch, where the current development version is odd-numbered (e.g. 1.19.x) and the upcoming release will be even-numbered (e.g. 1.20.0).

Usage

Invoke this skill when you want to draft or update a package NEWS file:

• "Update the NEWS file from recent commits"
• "Draft NEWS entries from git history"
• "Generate a changelog based on git commits"
• "Add a NEWS entry for the upcoming release"
• "Update NEWS based on what changed since the last release"

Prerequisites

• Working directory is an R package root (contains DESCRIPTION file)
• Directory is a git repository with commit history (git available on PATH)
• A NEWS file (NEWS.md, NEWS, or NEWS.Rd) may already exist, but is not required

Process

1. Detect NEWS File and Format

Check the package root for these files in priority order:

1. NEWS.md (markdown)
2. NEWS.Rd (R documentation format)
3. NEWS (plain text, Bioconductor-style)

If exactly one is found, use it. If multiple exist, ask the user which one to update. If none exist, ask which format to create (default: NEWS.md).

Record the detected file path and format for use throughout the remaining steps.

2. Read Package Version

Parse DESCRIPTION to extract the Version: field. In Bioconductor's versioning convention, the devel branch carries an odd minor version (the Y in X.Y.Z), while each released version has an even Y.

Examples:

• Current devel 1.19.4 → upcoming release is 1.20.0
• Current devel 2.5.7 → upcoming release is 2.6.0
• Current devel 0.99.3 → this is a new package submission (version below 1.0.0)

This derived release version will be the heading for the new NEWS block.

3. Determine Commit Range

Bioconductor packages do not use git tags for releases. Instead, the commit range is determined by searching the git log for a specific release-bump commit message.

Step 3a — Search for the release-bump commit

Run:

git log --oneline --all

Search for a commit whose message matches this exact literal pattern (these commits are applied en masse by Bioconductor and do not include the actual package version number):

bump x.y.z version to even y prior to creation of RELEASE_

For example, for the Bioconductor 3.18 release:

a1b2c3d bump x.y.z version to even y prior to creation of RELEASE_3_18 branch

Step 3b — Find the devel-version bump commit that follows

Immediately after the release-bump commit, Bioconductor applies a second en-masse commit that increments the devel branch back to an odd minor version. Its message matches the literal pattern:

bump x.y.z version to odd y following creation of RELEASE_

For example:

b2c3d4e bump x.y.z version to odd y following creation of RELEASE_3_18 branch

This second commit (<devel-bump-sha>) is the starting point for the commit range. Use <devel-bump-sha>..HEAD as the range.

To locate it, find the oldest commit returned by:

git log --oneline <release-bump-sha>..HEAD

Step 3c — Handle new packages (no release-bump commit found)

If no release-bump commit is found in the history:

1. Check the current Version: field from DESCRIPTION.
2. If the version is below 1.0.0 (e.g. 0.99.3): treat the entire commit history as the range (i.e. git log --oneline from the first commit to HEAD) and note that this appears to be a new package submission.
3. If the version is 1.0.0 or higher but no release-bump commit is found: do not guess. Ask the user to supply a starting commit SHA (see Error Handling).

Step 3d — Handle an existing NEWS entry for the upcoming release

If the NEWS file already has a section heading for the upcoming release version, offer to append new commits since the last commit already covered rather than regenerating the entire block.

Retrieve commits for the determined range:

git log <range> --oneline

Also retrieve merge commits separately:

git log <range> --merges --format="%H %s %b"

4. Extract PR Titles from Merge Commits

For each merge commit in the log, attempt to extract the pull request title:

• GitHub-style merge commits have the format: Merge pull request #NNN from <branch> followed by the PR title on the next line
• Parse the commit body (from git show <sha> --format="%b" -s) to extract the PR title
• If a PR title is found, use it as the primary description for that merge commit; otherwise fall back to the merge commit subject line

For non-merge commits, use the commit subject line directly.

Look up issue and PR authors: For each issue or pull request number referenced in the commit messages, merge commits, or PR titles (e.g. #1, Fixes #12, Addresses problem 1 in #1, Merge pull request #45), find the GitHub username of the person who opened it so the NEWS entry can credit them. Determine the repository from the BugReports or URL field in DESCRIPTION, falling back to the origin remote, then run:

gh api repos/<owner>/<repo>/issues/<number> --jq .user.login

The issues endpoint returns pull requests as well, so the same call works for both and gives the PR author for a PR.

If gh is unavailable, the repository is not on GitHub, or the lookup fails, keep the number without a username and flag the entry for review in step 10.

5. Classify Commits by Message Specificity

For each commit, evaluate its message for vagueness using these criteria — a commit is vague if it meets any of the following:

Word count rule: The commit message (after stripping conventional-commit type prefixes like fix:, feat:, chore:) contains 3 words or fewer.

Filler phrase rule: The lowercased message matches any of these patterns:

• Single words: fix, update, wip, cleanup, refactor, changes, misc, tweaks, improvements
• Short phrases: minor update, minor fix, minor changes, api update, small fix, small update, bug fix, quick fix, more fixes, various fixes, various changes

Split all commits into two lists: specific and vague.

6. Inspect Diffs for Vague Commits

For each vague commit, run:

git show <sha> --stat --patch -- R/ src/ DESCRIPTION NAMESPACE

Limiting the diff to code-bearing paths avoids noise from unrelated files.

From the diff, summarise:

• Files changed: list each changed file and whether it was added, deleted, or modified
• Functions affected: scan + and - diff lines for patterns such as function(, setGeneric(, setClass(, setMethod(, setRefClass(, R6Class(, export( — note added (+) vs removed (-) occurrences; this list is representative and agents may extend it based on what they observe in the diff
• Scale of change: lines added and removed

If a diff is very large (> 500 changed lines total), summarise by file rather than by line to avoid context overflow.

Generated files can change in layout without changing in meaning. For NAMESPACE in particular, a new roxygen2 version may regroup or reorder directives; compare the set of export(), import*(), and S3method() directives before and after rather than the diff lines, and treat a layout-only change as internal.

Combine the diff summary with the original vague commit message to produce an enriched description to use in subsequent steps.

7. Detect Existing NEWS Categories

If the NEWS file already exists, read its content and extract all unique category/section headings currently in use. Examples vary by package — typical headings include NEW FEATURES, BUG FIXES, SIGNIFICANT USER-VISIBLE CHANGES, DEPRECATED AND DEFUNCT, INTERNAL CHANGES, and others.

Use these detected headings as the allowed category set for the new entries. If no headings can be detected (e.g. the file is new or has no previous entries), present this default set for the user to choose from and allow custom headings:

• NEW FEATURES
• SIGNIFICANT USER-VISIBLE CHANGES
• BUG FIXES AND MINOR IMPROVEMENTS
• DEPRECATED AND DEFUNCT

The default set has no separate heading for internal changes; dependency, documentation, CI, and test changes go under BUG FIXES AND MINOR IMPROVEMENTS. Only include headings that receive entries.

Also record the style of the existing version headings (e.g. # pkgname 1.18.0 or # Changes in version 1.18.0) and bullet marker (* or -) so the new block matches them.

8. Categorise All Changes

For each commit (using the enriched description for previously vague commits), assign it to one of the detected categories:

• Assign based on the content of the message and diff:
  • New exported functions/classes/methods/vignettes → NEW FEATURES (or equivalent)
  • Bug/error/warning fixes, test changes → BUG FIXES AND MINOR IMPROVEMENTS (or BUG FIXES, or equivalent)
  • Removal of exports, Deprecated/defunct patterns → DEPRECATED AND DEFUNCT (or equivalent)
  • Breaking changes, renamed arguments, changed defaults → SIGNIFICANT USER-VISIBLE CHANGES (or equivalent)
  • Non-exported code, CI, documentation-only, DESCRIPTION-only → BUG FIXES AND MINOR IMPROVEMENTS (or INTERNAL CHANGES if the NEWS file already uses that heading)
• If a commit is ambiguous and cannot be confidently classified, assign it to the most conservative applicable category — typically BUG FIXES AND MINOR IMPROVEMENTS, or INTERNAL CHANGES or MISCELLANEOUS if the NEWS file already uses one of those — and always mark it with a # TODO: verify category annotation so the user can reclassify it during the preview step
• Omit commits that only change the Version: field in DESCRIPTION (manual version bumps and the Bioconductor release-bump commits); the version heading already records them
• Several commits about the same change (e.g. a fix and its follow-up tests) can be combined into one entry

9. Draft NEWS Entries

Group entries by category under the upcoming release version heading. Match the version heading style and bullet marker recorded in step 7; the examples below are for files with no previous entries.

Format entries according to the detected NEWS file format:

NEWS.md (markdown):

# Changes in version 1.20.0

## NEW FEATURES

- Description of new feature

## BUG FIXES AND MINOR IMPROVEMENTS

- Description of fix (#12, @username)

NEWS (plain text, Bioconductor-style):

        Changes in version 1.20.0 (YYYY-MM-DD)
        + NEW FEATURES
        o Description of new feature

        + BUG FIXES AND MINOR IMPROVEMENTS
        o Description of fix (#12, @username)

NEWS.Rd (R documentation format):

\section{Changes in version 1.20.0}{
  \subsection{NEW FEATURES}{
    \itemize{
      \item Description of new feature
    }
  }
  \subsection{BUG FIXES AND MINOR IMPROVEMENTS}{
    \itemize{
      \item Description of fix (#12, @username)
    }
  }
}

Each bullet/item:

• Is a concise one-liner derived from the commit message (or enriched description for previously vague commits)
• Is written for package users: say what changed in behaviour, not how the code changed
• Ends with an issue or PR number in parentheses only when the commit or PR references one, followed by the GitHub username of the person who opened that issue or PR, e.g. (#1, @username), to credit the reporter or contributor
• Does not include commit SHAs; the version heading tells users which release the change is in, and SHAs are noise for readers of NEWS
• Uses # TODO: verify category (NEWS.md/NEWS) or a comment equivalent to flag uncertain entries

10. Show Preview and Confirm

Display the complete drafted NEWS block in the chat. Also provide a brief summary:

• Total commits processed
• Number of commits that needed diff inspection
• Breakdown of entries by category
• Any entries flagged for manual review, including issues or PRs whose author could not be looked up

Ask for confirmation before writing:

Does this NEWS draft look correct?
  [yes] - write to <filename>
  [edit] - specify which entries to revise
  [abort] - discard and exit

If the user requests edits, apply them interactively and show the updated preview again before writing.

Do not write to disk until the user confirms.

11. Write NEWS File

Once confirmed:

• Prepend the new version block to the existing NEWS file (new releases go at the top)
• If no NEWS file existed, create it with just the new block
• Confirm with: ✅ NEWS updated for version X.Y.Z — N entries across K categories written to <filename>

Output Format

• A drafted NEWS block displayed in the chat for review prior to any file writes
• Upon user confirmation, the updated (or newly created) NEWS.md, NEWS, or NEWS.Rd file on disk

Error Handling

• Not an R package directory (DESCRIPTION missing): abort with "No DESCRIPTION file found — run this skill from an R package root"
• Not a git repository: abort with "No git repository found — initialise git first"
• git not on PATH: abort with "git is not available — install git and ensure it is on your PATH"
• No commits in range: report "No new commits since <starting-commit> — NEWS is already up to date"
• No release-bump commit and version ≥ 1.0.0: prompt the user to supply a starting commit SHA; do not guess
• No release-bump commit and version < 1.0.0: use full history and note this appears to be a new package submission
• Multiple NEWS files found: list them and ask user which to update
• Diff too large (> 500 changed lines for a single commit): summarise by file, note the limitation

Examples

Example 1: Clean Commit History

Invocation: "Update the NEWS file from recent commits"

Scenario: Package with prior releases; all commits since the previous release have descriptive messages.

Process:

1. Finds NEWS.md, detects existing headings NEW FEATURES and BUG FIXES
2. Derives release version 1.20.0 from current devel 1.19.4
3. Finds release-bump commit "bump x.y.z version to even y prior to creation of RELEASE_3_18 branch", then locates the subsequent devel-bump commit "bump x.y.z version to odd y following creation of RELEASE_3_18 branch" (b2c3d4e)
4. Retrieves 12 commits in range b2c3d4e..HEAD — none are vague
5. Categorises and drafts 12 entries
6. Shows preview, user confirms
7. Prepends block to NEWS.md

Example 2: Vague Commits Needing Diff Inspection

Invocation: "Generate a changelog based on git commits"

Scenario: Several commits have messages like "API update", "fix", and "wip".

Process:

1. Finds NEWS.md; locates release-bump and subsequent devel-bump commit
2. Retrieves 8 commits in range: 5 specific, 3 vague
3. For "API update" (commit a1b2c3d): inspects diff, finds returnSamples() signature changed — classifies as SIGNIFICANT USER-VISIBLE CHANGES
4. For "fix" (commit e4f5a6b): inspects diff, finds test file edit — classifies as BUG FIXES AND MINOR IMPROVEMENTS
5. For "wip" (commit c7d8e9f): diff shows only internal helper changes — classifies as BUG FIXES AND MINOR IMPROVEMENTS
6. Drafts preview noting 3 commits were diff-inspected
7. User confirms; file updated

Example 3: New Package Submission (version < 1.0.0)

Invocation: "Add a NEWS entry for the upcoming release"

Scenario: New package submission; DESCRIPTION shows Version: 0.99.3; no release-bump commit exists.

Process:

1. No NEWS file found; asks user which format to create → user selects NEWS.md
2. No release-bump commit found; version is 0.99.3 (below 1.0.0) — treat entire commit history as the range
3. Drafts first-ever NEWS block noting this is a new package submission
4. Shows preview, user confirms
5. Creates NEWS.md with the new block

Example 4: No Release-Bump Commit but Version ≥ 1.0.0

Invocation: "Update the NEWS file"

Scenario: Package is at 1.3.2 on devel but has no release-bump commit (e.g. history was rewritten or imported without full history).

Process:

1. Searches git log — no commit matching the release-bump pattern is found
2. Version is 1.3.2 (≥ 1.0.0) — cannot determine range safely
3. Tells the user: "No release-bump commit was found and the version is ≥ 1.0.0. Please specify a commit SHA to use as the starting point for the diff and NEWS entry generation."
4. User provides f9e8d7c; skill uses f9e8d7c..HEAD as the range and proceeds normally

Example 5: PR Titles Used

Invocation: "Draft NEWS entries from git history"

Scenario: Repository uses GitHub pull requests merged with squash-merge.

Process:

1. Locates release-bump and devel-bump commits to establish range
2. Merge commits parsed; PR titles extracted (e.g. "Add support for TreeSummarizedExperiment input" from PR #45)
3. PR title used in place of merge commit subject "Merge pull request #45 from feature-branch"
4. Looks up the PR author with gh api repos/<owner>/<repo>/issues/45 --jq .user.login
5. Richer, human-readable entries appear in draft with a (#45, @username) reference crediting the PR author

Notes

• This skill assumes the Bioconductor convention where the devel branch carries odd-numbered minor versions and each release has an even minor version; no git tags are used or required
• The commit range is derived from the release-bump commit pattern ("bump x.y.z version to even y prior to creation of RELEASE_..."); if that pattern is absent and the version is ≥ 1.0.0, the user must supply a starting commit SHA
• Category headings, the version heading style, and the bullet marker are inferred from the existing NEWS file; no new heading names are introduced unless the file has no headings yet or the user requests them
• Entries reference issues and PRs but not commit SHAs; each reference credits the GitHub username of the person who opened the issue or PR
• Looking up authors uses gh and network access; without them, entries keep the number only
• Diff inspection is scoped to R/, src/, DESCRIPTION, and NAMESPACE to avoid irrelevant noise from documentation or test-only commits
• The skill does not run R or install packages; it relies on git, file reads, and gh for issue and PR authors
• For large repositories with hundreds of commits, consider narrowing the range manually if the preview is unwieldy

Related: See analyze-r-package for package structure analysis. See SKILL_STANDARD.md for skill format details.