Skip to content

Commit 0f7318c

Browse files
tzanko-matevtzanko-matev
committed
WS4
1 parent 121a9c8 commit 0f7318c

File tree

5 files changed

+149
-4
lines changed

5 files changed

+149
-4
lines changed

‎.github/ISSUE_TEMPLATE/recorder-release.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Recorder Release Tracker
2+
description: Plan, execute, and verify a codetracer-python-recorder release
3+
title: "Release: codetracer-python-recorder vX.Y.Z"
4+
labels: ["release", "codetracer-python-recorder"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: >
9+
Use this issue to coordinate a release of `codetracer-python-recorder`.
10+
Follow the release checklist in `design-docs/codetracer-python-recorder-pypi-release-checklist.md`
11+
and record progress below.
12+
- type: input
13+
id: version
14+
attributes:
15+
label: Target version
16+
description: The version you plan to publish (e.g., 0.2.0)
17+
placeholder: 0.2.0
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: planning
22+
attributes:
23+
label: Pre-release planning notes
24+
description: Capture any blockers, feature highlights, or coordination tasks.
25+
placeholder: >
26+
- Pending PRs
27+
- Docs to update
28+
- Coordination with downstream teams
29+
- type: checkboxes
30+
id: checklist
31+
attributes:
32+
label: Checklist
33+
description: >
34+
Tick each item as you complete the steps in the release checklist.
35+
Reference links or PRs next to each item where useful.
36+
options:
37+
- label: Changelog updated and version bumped (pyproject.toml / Cargo.toml)
38+
- label: Local validation complete (`just test`, `just smoke-wheel`)
39+
- label: Annotated tag pushed (`recorder-vX.Y.Z`)
40+
- label: TestPyPI workflow run passed and smoke install verified
41+
- label: PyPI promotion approved and workflow completed
42+
- label: Post-release validation on Linux, macOS, Windows (3.12 / 3.13)
43+
- label: Release notes published and stakeholders notified
44+
- type: textarea
45+
id: retrospective
46+
attributes:
47+
label: Post-release notes
48+
description: >
49+
Document any follow-up work, incidents, or improvements spotted during the release.
50+
placeholder: >
51+
- Follow-up issue: ...
52+
- Automation improvement: ...

‎codetracer-python-recorder/CHANGELOG.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Changelog
2+
3+
All notable changes to `codetracer-python-recorder` will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2025-10-13
9+
10+
### Added
11+
- Initial public release of the Rust-backed recorder with PyO3 bindings.
12+
- Python façade (`codetracer_python_recorder`) exposing `start`, `stop`, `trace`,
13+
and CLI entry point (`python -m codetracer_python_recorder`).
14+
- Support for generating `trace_metadata.json` and `trace_paths.json`
15+
artefacts compatible with the Codetracer db-backend importer.
16+
- Cross-platform packaging definition targeting CPython 3.12 and 3.13 on
17+
Linux (manylinux2014 `x86_64`/`aarch64`), macOS universal2, and Windows `amd64`.
18+
19+
[0.1.0]: https://github.com/metacraft-labs/cpr-main/releases/tag/recorder-v0.1.0

‎design-docs/codetracer-python-recorder-pypi-release-checklist.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,23 @@
77
- Bump the version in both `codetracer-python-recorder/pyproject.toml` and `codetracer-python-recorder/Cargo.toml`.
88
- Run `python scripts/check_recorder_version.py` to confirm parity.
99
- Regenerate or update documentation if required (`README.md`, API docs).
10+
- Add a changelog entry in `codetracer-python-recorder/CHANGELOG.md` summarising the release.
1011
3. **Validate locally**
1112
- Execute `just venv 3.12 dev` (or preferred interpreter) and run `just test`.
1213
- Build wheels and sdist (`just build` or `maturin build --release --sdist`) and perform a smoke install in a clean virtualenv (`python -m pip install dist/*.whl` and run `python -m codetracer_python_recorder --help`).
1314
4. **Prepare the release tag**
14-
- Commit changes following Conventional Commits.
15-
- Tag the release with `git tag -a recorder-vX.Y.Z -m "codetracer-python-recorder vX.Y.Z"` and push (`git push origin recorder-vX.Y.Z`).
15+
- Commit changes following Conventional Commits (`feat:`/`fix:` etc.).
16+
- Run `git tag -a recorder-vX.Y.Z -m "codetracer-python-recorder vX.Y.Z"` and push with `git push origin recorder-vX.Y.Z`.
17+
- If a dry run is required, trigger `workflow_dispatch` on the release workflow with the desired tag before creating it.
1618
5. **Trigger CI publishing**
1719
- Monitor the `recorder-release` workflow.
1820
- Verify that TestPyPI publishing succeeds and smoke tests pass on all platforms.
1921
6. **Promote to PyPI**
2022
- Approve the protected “Promote to PyPI” environment to publish the previously built artefacts.
2123
- Confirm the workflow completes without errors.
2224
7. **Post-release tasks**
23-
- Validate installation directly from PyPI on Linux, macOS, and Windows for Python 3.12 and 3.13.
24-
- Publish release notes (GitHub Release) and notify stakeholders.
25+
- Validate installation directly from PyPI on Linux, macOS, and Windows for Python 3.12 and 3.13 (`pip install codetracer-python-recorder && python -m codetracer_python_recorder --help`).
26+
- Publish or update release notes on GitHub (linking to `CHANGELOG.md`) and notify stakeholders.
2527
- Create follow-up issues for any tasks deferred from the release.
2628

2729
Refer to the Python Packaging User Guide packaging flow (<https://packaging.python.org/en/latest/flow/>)

‎design-docs/codetracer-python-recorder-pypi-release-implementation-plan.status.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,11 @@
1717
- ✅ Integrated artefact collection plus a TestPyPI smoke install that exercises the CLI before invoking Trusted Publishing-friendly uploads.
1818
- ✅ Added a guarded PyPI promotion job that reuses the staged artefacts and requires environment approval prior to publishing.
1919

20+
## Workstream 4 – Operational readiness & documentation
21+
- ✅ Created `codetracer-python-recorder/CHANGELOG.md` and wired the release checklist to keep it current.
22+
- ✅ Expanded the release checklist with explicit tagging commands and cross-platform post-release validation steps.
23+
- ✅ Added a GitHub issue template (`.github/ISSUE_TEMPLATE/recorder-release.yml`) to coordinate future releases using the documented checklist.
24+
- ✅ Documented operational procedures and Trusted Publishing details in `design-docs/codetracer-python-recorder-release-operations.md`.
25+
2026
## Next Tasks
2127
- First tagged release should monitor the new workflow end-to-end and capture any follow-up improvements in the release tracker issue.

‎design-docs/codetracer-python-recorder-release-operations.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# `codetracer-python-recorder` Release Operations
2+
3+
This note supplements the release checklist with details about the automated workflow,
4+
Trusted Publishing setup, and manual approvals required to promote artefacts from
5+
TestPyPI to PyPI.
6+
7+
## GitHub Actions workflow
8+
9+
- Workflow file: `.github/workflows/recorder-release.yml`.
10+
- Triggers:
11+
- `workflow_dispatch` – run a staged release without creating a tag. Supply the
12+
target ref (branch/tag) and monitor the jobs; artefacts are still produced but
13+
PyPI promotion is skipped unless the ref is a tagged release.
14+
- `push` to tags matching `recorder-v*`.
15+
- Job sequence:
16+
1. `verify` (ubuntu) – prepares the dev environment via Nix, runs `just test`,
17+
and confirms Python/Rust version parity.
18+
2. `build` matrix (linux-x86_64, linux-aarch64, macos-universal2, windows-amd64) –
19+
uses maturin to build wheels (and the sdist on linux-x86_64) and uploads artefacts.
20+
3. `publish-testpypi` – aggregates artefacts, performs a Linux smoke install using
21+
`scripts/select_recorder_artifact.py`, then publishes to TestPyPI.
22+
4. `publish-pypi` – gated behind the protected environment. Runs only for tag pushes
23+
after manual approval, reusing artefacts from earlier jobs.
24+
25+
## Trusted Publishing configuration
26+
27+
- TestPyPI and PyPI both list `metacraft-labs/cpr-main` as a Trusted Publisher.
28+
- The workflow requests OIDC tokens automatically; no API tokens are stored in secrets.
29+
- GitHub environments:
30+
- `testpypi` – no approval required; used to track audit logs and enforce environment
31+
level variables if needed.
32+
- `pypi-production` – requires manual approval by a Release Engineer before the
33+
`publish-pypi` job starts. Approvers can approve directly from the workflow run UI.
34+
35+
## Maintainer checklist highlights
36+
37+
1. **Before dispatching the workflow**
38+
- Update version numbers in `pyproject.toml` and `Cargo.toml`.
39+
- Append a section to `codetracer-python-recorder/CHANGELOG.md`.
40+
- Ensure `python3 scripts/check_recorder_version.py` succeeds.
41+
- Optionally run `just smoke-wheel` locally.
42+
43+
2. **Running the workflow**
44+
- For dry runs (no tagging yet) use `workflow_dispatch` targeting the release branch.
45+
- For real releases, push the annotated tag (`recorder-vX.Y.Z`). The workflow validates
46+
the tag against the pyproject version.
47+
48+
3. **Approvals**
49+
- Watch the `publish-testpypi` job; ensure the smoke install step passes.
50+
- Approve the `pypi-production` environment to trigger promotion. Include a note in the
51+
approval dialog referencing the TestPyPI run result.
52+
53+
4. **Post-release**
54+
- Install from PyPI on Linux/macOS/Windows for Python 3.12 and 3.13
55+
(`pip install codetracer-python-recorder && python -m codetracer_python_recorder --help`).
56+
- Publish GitHub release notes that link back to the changelog entry.
57+
- Close the release tracker issue once validation is complete.
58+
59+
## Fallback procedure
60+
61+
If the workflow cannot obtain an OIDC token (e.g., PyPI incidents):
62+
63+
1. Temporarily disable the Trusted Publishing requirement in PyPI/TestPyPI.
64+
2. Configure a scoped API token as an environment secret and rerun the failed publish job.
65+
3. Re-enable Trusted Publishing immediately after resolving the incident.
66+
4. Document the incident in the release tracker issue.

0 commit comments

Comments
 (0)