| name | finalize-pr |
| description | Finalize a feature branch for merge. Use when finishing a feature branch, preparing for merge, releasing a new version, bumping the version, adding a changelog entry, or when asked to finalize, wrap up, or close out a PR. Covers version bump across all files, CHANGELOG entry, Sphinx + README updates, editor-lens pass over the diff, lint, and test verification. Replaces the older version-bump skill. |
| argument-hint | Optional: target version (e.g. '0.7.0'); otherwise inferred from scope of changes |
Finalize PR
Prepares a feature branch for merge by bumping the version, writing a
changelog entry, updating documentation, scrubbing comment debt, and
verifying the change with lint + the full test suite. The user reviews
and commits — this skill never commits.
When to Use
- A feature branch is ready to merge and needs the final release polish
- Bumping the bocpy version (replaces the older
version-bump skill)
- Adding a CHANGELOG entry
- Pre-merge documentation sweep
For a multi-perspective pre-merge review of the code itself, run
branch-review first. This skill assumes the code is settled and the
test suite is green.
Prerequisites
Before invoking this skill:
- All code changes are complete
- The test suite passes locally in the venv you intend to use
- A
branch-review pass (or equivalent) has been run if the change is
non-trivial — see .github/copilot-instructions.md
- You know which venv this work targets (
.env312, .env313d,
.env313t, .env314, .env315, .env315t). Ask the user if
unsure; default is .env314.
Procedure
Execute these steps in order. Pause for user review between steps —
this is a wrap-up workflow, not an autonomous one.
Step 1 — Determine What Changed
Gather context about the branch:
- Read the current version from
pyproject.toml ([project] version).
- Run
git log --oneline main..HEAD to see commits on the branch.
- Run
git diff main --stat to see changed files.
- Read the current
CHANGELOG.md to see the most recent entry format
and any existing ## Unreleased section.
- If a session plan file exists under
.copilot/plans/ for this
branch, read it to understand the scope of work.
Summarize the work performed (what was added, what was changed, what
was removed, any breaking changes) and confirm with the user before
proceeding. The summary drives every later step.
Step 2 — Choose the New Version
bocpy follows semantic versioning. Propose the version bump based on
the Step 1 summary:
| Bump | When |
|---|
Patch (0.6.0 → 0.6.1) | Bug fixes, internal refactors, test additions, doc-only changes, no public API change |
Minor (0.6.0 → 0.7.0) | New public API (new @when semantics, new bocpy.* symbols, new C ABI surface), new examples, new tunables. No breaking changes |
Major (0.6.0 → 1.0.0) | Breaking changes to the Python API, the C ABI (<bocpy/bocpy.h> / <bocpy/xidata.h>), or Cown / @when semantics |
The public C ABI is version-gated via the BOCPY_ABI macro and the
bocpy~=MAJOR.MINOR pin in templates/c_abi_consumer/pyproject.toml.
Any incompatible change to <bocpy/bocpy.h> or <bocpy/xidata.h>
requires a minor bump at minimum and an explicit BOCPY_ABI bump in
the header.
Confirm the proposed version with the user before editing any files.
Step 3 — Bump the Version
Update all five files in lock-step. Skipping any one of these
leaves the release inconsistent.
3.1 pyproject.toml
[project]
name = "bocpy"
version = "<NEW_VERSION>"
3.2 sphinx/source/conf.py
release = '<NEW_VERSION>'
3.3 CITATION.cff
Update both fields:
version: <NEW_VERSION>
date-released: <TODAY YYYY-MM-DD>
3.4 templates/c_abi_consumer/pyproject.toml
Update both bocpy entries to a compatible-release bound on the new
MAJOR.MINOR:
[build-system]
requires = ["setuptools", "wheel", "bocpy~=<MAJOR.MINOR>"]
[project]
dependencies = ["bocpy~=<MAJOR.MINOR>"]
The template is the canonical downstream example; its pin signals
which public C ABI it was authored against. Keep it in lock-step with
the root [project].version.
3.5 CHANGELOG.md
Handled in Step 4 — version is part of the changelog entry header.
Step 4 — Add a CHANGELOG Entry
Open CHANGELOG.md. If a ## Unreleased section already exists,
re-title it; otherwise prepend a new entry at the top of the file
(below any header).
Format
Match the prevailing format in the file. Recent entries follow this
shape:
## YYYY-MM-DD - Version X.Y.Z
One-paragraph summary of the headline change.
**New Features**
- **Feature name** — what it is, why it matters, where it lives.
- ...
**Bug Fixes**
- **Short title** — root cause + fix, in past tense.
- ...
**Improvements**
- ...
**Breaking Changes**
- **What broke** — why, and the recommended migration path.
**Documentation**
- New :doc:`xxx` page, expanded :doc:`api`, ...
**Tests**
- ...
**Internal**
- ...
Rules
- Date is today's date (UTC).
- Use the same bold-noun-phrase + em-dash style as recent entries.
- Reference Sphinx pages with
:doc: directives (rendered on the
Sphinx site, which embeds the changelog).
- Group by category in the order shown above. Omit any category with
no entries.
- Breaking Changes must be its own section, never folded into
another. Each entry must say what to do instead.
- Mention any new console entry points (
bocpy-*) by name.
- Mention any new files in
templates/c_abi_consumer/ only if they
change the consumer-facing template.
Step 5 — Update Documentation
Walk through the docs and update anything the branch made stale. Do
not rewrite prose that is still accurate.
5.1 README.md (root)
Check and update:
- Public API table / feature list — add new
@when, Cown,
send/receive, noticeboard, or messaging symbols.
- Quick-start / examples list — add any new entry-point example
(
bocpy-* console script).
- Compatibility matrix — update if Python-version support
changed (look at
pyproject.toml classifiers).
- Sub-interpreter / scheduler description — update only if the
architecture changed meaningfully on this branch.
The file is PyPI's project description (after the
<!-- pypi-skip-start -->...<!-- pypi-skip-end --> filter in
setup.py); keep it presentable.
5.2 sphinx/source/
| File | Update if... |
|---|
index.rst | Architecture overview changed, or a new top-level subsystem was added |
api.rst | New public Python symbol added or removed (Sphinx autodoc picks the docstring up from __init__.pyi, but the toctree entry must exist) |
c_abi.rst | Anything in <bocpy/bocpy.h> or <bocpy/xidata.h> changed, or BOCPY_ABI was bumped |
messaging.rst | send / receive / set_tags / drain / TIMEOUT semantics changed |
noticeboard.rst | notice_* / noticeboard() / REMOVED / snapshot semantics changed |
sbom.rst | SBOM generation, the audit extra, or wheel-embedding format changed |
Sphinx autodoc reads docstrings from src/bocpy/__init__.pyi and
src/bocpy/_core.pyi. If you added a new public symbol, the stub
docstring is the canonical source — update it there, not in
behaviors.py (or both, where applicable).
5.3 templates/c_abi_consumer/README.md
Update only if the consumer-facing API surface changed (new helpers
in bocpy.get_include() / bocpy.get_sources(), new headers, new
required compile flags).
Step 6 — Editor-Lens Pass Over the Diff
Comment debt accumulates while a PR is in flight: review-process
scaffolding (chunk numbers, finding IDs like H1 / M5 / L2,
plan back-references, sketch IDs, "Round-2 adv#6"), wordy paraphrases
of the code, dated status notes, and "previously / now" archaeology.
None of this serves a future reader. Scrub it as part of finalize.
This step is run via the review-loop skill against the PR diff
(not the whole repo) using the editor-lens agent.
-
Identify the changed in-scope source files:
mkdir -p .copilot/finalize
git diff --name-only main -- \
'src/bocpy/**/*.c' 'src/bocpy/**/*.h' \
'src/bocpy/**/*.py' 'src/bocpy/**/*.pyi' \
'examples/**/*.py' \
'test/**/*.py' \
'templates/c_abi_consumer/src/**/*.c' \
'templates/c_abi_consumer/src/**/*.h' \
'templates/c_abi_consumer/src/**/*.py' \
'scripts/**/*.py' \
| tee .copilot/finalize/editor-lens-targets.txt
git diff (no ..HEAD) covers both committed and uncommitted
changes — important during finalize, when you may still be editing.
-
Invoke review-loop with editor-lens as the reviewer and the
file list as the target. The lens follows the keep / rewrite / cut
policy in .github/agents/editor-lens.agent.md. Iterate until the
loop comes back clean.
-
Apply approved cuts and rewrites. Anything the lens flags under
"Questions for the user" must be resolved before proceeding — do
not silently delete.
The editor-lens scope explicitly excludes sphinx/source/,
README.md, CHANGELOG.md, the top-level policy docs, and
everything under .github/ and .copilot/. Those have different
rules and are managed by other steps in this skill (or are off-limits
entirely).
Why this lives in finalize, not pre-commit: during PR work the
review tags and scaffold comments are useful — they let the author
and reviewer cross-reference findings. They become noise only after
the review documents are deleted. Finalize is the right place to
scrub.
Step 7 — Lint and Test
Activate the chosen venv (default .env314 — confirm with the user)
and run the full local mirror of the PR gate. Pipe long-running
output to .copilot/finalize/<name>.log so the chat stays readable.
source .env314/bin/activate
7.1 Lint
Mirrors the .github/workflows/pr_gate.yml linting job. The
--filename flag opts the walker into .pyi stubs (it would
otherwise skip them silently):
flake8 --filename='*.py,*.pyi' src/bocpy test examples scripts \
2>&1 | tee .copilot/finalize/flake8.log
Must exit zero.
7.2 Clang-format
Mirrors the cpp-format job. Run for both C trees touched by the
branch:
clang-format-18 --dry-run -Werror \
src/bocpy/*.c src/bocpy/*.h src/bocpy/include/bocpy/*.h \
2>&1 | tee .copilot/finalize/clang-format-src.log
clang-format-18 --dry-run -Werror \
templates/c_abi_consumer/src/**/*.{c,h} \
2>&1 | tee .copilot/finalize/clang-format-template.log
Both must exit zero. If clang-format-18 is not installed, install
it (apt install clang-format-18) or skip with explicit user
approval; the CI version is pinned to 18.
7.3 Reinstall bocpy in the venv
A version bump touches pyproject.toml and (often) C sources. Force
a fresh editable install so the test suite sees the new build. Use
the BOCPY_BUILD_INTERNAL_TESTS=1 opt-in so the
_internal_test_* extensions are built and the
test_internal_* / test_compat_atomics.py modules run instead
of skipping:
BOCPY_BUILD_INTERNAL_TESTS=1 pip install -e .[test] --no-build-isolation \
2>&1 | tee .copilot/finalize/install.log
7.4 Full test suite
pytest -vv 2>&1 | tee .copilot/finalize/pytest.log | tail -40
Must exit zero. If pre-existing skips are present (e.g.
version-gated tests), confirm they match the baseline recorded in
the session plan; new skips warrant investigation.
7.5 Downstream consumer (if touched)
If the branch changed anything under src/bocpy/include/bocpy/,
src/bocpy/boc_*.{c,h}, templates/c_abi_consumer/, or the
bocpy.get_include() / bocpy.get_sources() helpers, also run:
pip install --no-build-isolation ./templates/c_abi_consumer \
2>&1 | tee .copilot/finalize/consumer-install.log
pytest -vv templates/c_abi_consumer/test \
2>&1 | tee .copilot/finalize/consumer-pytest.log | tail -20
Both must exit zero.
7.6 Cross-version spot check (optional)
If the branch touched anything version-gated (xidata.h,
PY_VERSION_HEX ladders, free-threaded code paths,
#if Py_GIL_DISABLED branches), re-run 7.3 + 7.4 in at least one
additional venv covering the affected versions
(e.g. .env312, .env313t, .env315t). Confirm with the user
which extra venvs to exercise.
Step 8 — Summarize
Present a single summary to the user with:
- Version: old → new
- Files changed by this skill:
pyproject.toml,
sphinx/source/conf.py, CITATION.cff,
templates/c_abi_consumer/pyproject.toml, CHANGELOG.md,
any Sphinx pages updated, any README sections updated, and the
list of source files edited by the editor-lens pass.
- Verification:
flake8, clang-format, pytest, downstream
consumer (if run), cross-version (if run) — all pass / fail with
log paths under .copilot/finalize/.
- Open questions: anything
editor-lens flagged as ambiguous
and any pre-existing test skips that warrant attention.
Do not commit. All git operations belong to the user.
Guardrails
- Never commit, push, tag, or create a release. The user owns
every git operation.
- Never skip a file listed in Step 3. All five (
pyproject.toml,
conf.py, CITATION.cff, the template pyproject.toml, and
CHANGELOG.md) must move in lock-step.
- Never silently widen scope. If the editor-lens pass surfaces a
bug, stop and raise it as a finding; do not fix it in the finalize
pass.
- Never edit prose under
sphinx/source/ to mask a missing public
symbol. If the docs reference a symbol that does not exist, the
bug is in the code or in __init__.pyi, not the docs.
- Always confirm the venv at Step 7 before running
pip install.
Installing into the wrong venv silently rebuilds the wrong
interpreter's wheel.
