| name | update-updating |
| description | Add an entry to the UPDATING file at the repository root. Use whenever there is a security fix, vendor/third-party software update, behavioral change requiring user action, new stable branch creation, or a release. The UPDATING commit must be separate from any code changes so it can be cleanly cherry-picked to other branches. |
Update UPDATING
Use this skill when any of the following occur and need to be recorded for
users who track -current or a stable branch:
- Security vulnerability fixes (include CVE numbers when available)
- Vendor/third-party software version bumps
- Behavioral changes that require user action or awareness
- Creation of a new stable branch (e.g.,
stable/4.1)
- A release off a stable branch
Format rules
- Date header:
YYYYMMDD: on its own line, no leading whitespace
- Each entry: one leading tab character (not spaces), then the text
- Maximum line length: 80 characters (including the leading tab)
- Wrap long lines: continuation lines use a leading tab plus enough spaces
to align naturally with the text above
- Newer dates appear near the top of the file, below the header line
- Multiple entries under the same date are separated by a blank line
- CVE numbers should be included when applicable:
CVE-YYYY-NNNNN
- For vendor updates, just state the package name and version number
- For branch creation:
stable/X.Y branch created.
- For a release:
MidnightBSD X.Y released off stable/X.Y.
Example entries
20260607:
libarchive 3.8.7
expat 2.8.1: CVE-2026-45186
20260522:
libcasper: CVE-2026-39461 select(2) file descriptor set overflow
causes stack overflow
unbound 1.24.2: CVE-2025-11411
20250929:
stable/4.0 branch created.
Workflow
Step 1 — Gather information
Ask the user what needs to be recorded. Determine:
- Type: security fix / vendor update / behavioral change /
branch creation / release
- Date: use today's date (
date +%Y%m%d) unless the user specifies
a different date (e.g., the date a change actually landed)
- Content: the entry text — package name, version, CVE, or
description
date +%Y%m%d
Step 2 — Check for an existing entry for this date
head -20 UPDATING
If a YYYYMMDD: block for today already exists, the new entry will be
added to it (separated by a blank line from existing entries). If not, a
new date block is inserted at the top.
Step 3 — Verify the current branch and working tree
git branch --show-current
git status
Warn the user if there are uncommitted code changes — the UPDATING commit
must be separate. If uncommitted changes are present, ask whether to stash
them first or whether to proceed anyway.
Step 4 — Draft the entry
Draft the entry text following the format rules:
- Leading tab on every line
- No line exceeds 80 characters (tab counts as 1 character for this check)
- CVE numbers included if applicable
- Terse but complete — users need to know what changed and why it matters
Show the draft to the user:
"Here is the proposed UPDATING entry:
20260607:
\tlibarchive 3.8.7
Does this look correct, or would you like to change the wording?"
Wait for confirmation or corrections before proceeding.
Step 5 — Write the entry
Insert the entry at the top of UPDATING (after the file header line).
If today's date block already exists: append the new entry (with a
separating blank line) inside that block.
If today's date block does not exist: prepend a new block above the
previous newest entry.
Use this bash pattern to check and insert:
TODAY=$(date +%Y%m%d)
if grep -q "^${TODAY}:" UPDATING; then
echo "Today's block exists — appending entry."
else
echo "No block for today — creating new date header."
fi
Since precise multi-line insertion is error-prone in shell, edit the
file directly using the Edit tool: read the current top of UPDATING,
construct the new content, and write it back with the new entry in place.
Always read the file first, then use the Edit tool to make the change.
Step 6 — Show the diff and ask for approval
git diff UPDATING
STOP. Show the diff to the user and ask:
"The diff above shows the proposed UPDATING entry. Shall I commit this
as a separate commit?"
Step 7 — Commit separately
STOP before committing. If there are staged or unstaged code changes
unrelated to UPDATING, remind the user:
"There are other uncommitted changes in the working tree. The UPDATING
entry should be committed separately so it can be cleanly cherry-picked
to stable branches. I will only stage and commit UPDATING."
Then commit only UPDATING:
git add UPDATING
git commit -m "UPDATING: note <brief description>"
Commit message format: UPDATING: note <what changed>. Examples:
UPDATING: note libarchive 3.8.7UPDATING: note expat 2.8.1 CVE-2026-45186UPDATING: note stable/4.1 branch creationUPDATING: note iconv fix and mmap security fix
Step 8 — Cherry-pick to stable branches (optional)
Ask the user:
"Should this UPDATING entry also be cherry-picked to any stable
branches (e.g., stable/4.1, stable/4.0)?"
If yes, for each branch:
git checkout stable/X.Y
git cherry-pick <commit-hash>
STOP. Ask for approval before pushing each branch.
git push origin stable/X.Y
Then return to the original branch:
git checkout <original-branch>
When to add UPDATING entries
| Event | Example entry |
|---|
| Security fix (with CVE) | libarchive 3.8.7: CVE-2026-45123 |
| Security fix (no CVE) | dhcp: fix remote code execution via BOOTP field |
| Vendor update (no security) | mport 2.7.9 |
| Behavioral change | rtld: honor FreeBSD no-init notes |
| Kernel driver update | Update ice(4) driver to ice-1.3.41.0 |
| New stable branch | stable/4.1 branch created. |
| Release | MidnightBSD 4.1 released off stable/4.1. |
| Certificate update | caroot: update trusted/blacklisted certificates |
| Timezone update | tzdata 2025c |
What does NOT need an UPDATING entry
- Internal refactors with no user-visible effect
- Test-only changes
- CI/workflow changes
- Documentation-only changes
- Changes to
skills/ or agent config files
