docs(pdftract-2x7y): add verification note for pdftract-github-release
Documents the implementation of the pdftract-github-release WorkflowTemplate, including artifact taxonomy, release notes generation, and acceptance criteria status. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
jedarden
parent
89d16a6a59
commit
5485a15550
1 changed files with 111 additions and 0 deletions
111
notes/pdftract-2x7y.md
Normal file
111
notes/pdftract-2x7y.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
# pdftract-2x7y: pdftract-github-release WorkflowTemplate
|
||||
|
||||
## Summary
|
||||
|
||||
Authored the `pdftract-github-release` WorkflowTemplate at `k8s/iad-ci/argo-workflows/pdftract-github-release.yaml` in `jedarden/declarative-config`.
|
||||
|
||||
## Implementation
|
||||
|
||||
### Template Structure
|
||||
|
||||
The template orchestrates the final GitHub Release creation for milestone tags. It consists of a DAG with the following steps:
|
||||
|
||||
1. **setup** - Clone repo at tag commit
|
||||
2. **collect-artifacts** - Collect artifacts from upstream workflows or download from GitHub
|
||||
3. **compute-sha256sums** - Generate aggregate SHA256SUMS file
|
||||
4. **sign-sums** - Sign SHA256SUMS with cosign (keyless OIDC)
|
||||
5. **git-cliff-notes** - Generate release notes via git-cliff
|
||||
6. **gh-release-create** - Create GitHub Release with all artifacts
|
||||
|
||||
### Artifacts Attached to Release
|
||||
|
||||
- 10 binary archives (5 triples × 2 feature variants):
|
||||
- `pdftract-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz`
|
||||
- `pdftract-full-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz`
|
||||
- `pdftract-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz`
|
||||
- `pdftract-full-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz`
|
||||
- `pdftract-vX.Y.Z-x86_64-apple-darwin.tar.gz`
|
||||
- `pdftract-full-vX.Y.Z-x86_64-apple-darwin.tar.gz`
|
||||
- `pdftract-vX.Y.Z-aarch64-apple-darwin.tar.gz`
|
||||
- `pdftract-full-vX.Y.Z-aarch64-apple-darwin.tar.gz`
|
||||
- `pdftract-vX.Y.Z-x86_64-pc-windows-gnu.zip`
|
||||
- `pdftract-full-vX.Y.Z-x86_64-pc-windows-gnu.zip`
|
||||
|
||||
- 5 Python wheels + 1 sdist:
|
||||
- `pdftract-X.Y.Z-cp311-abi3-manylinux_2_28_x86_64.whl`
|
||||
- `pdftract-X.Y.Z-cp311-abi3-manylinux_2_28_aarch64.whl`
|
||||
- `pdftract-X.Y.Z-cp311-abi3-macosx_11_0_x86_64.whl`
|
||||
- `pdftract-X.Y.Z-cp311-abi3-macosx_11_0_arm64.whl`
|
||||
- `pdftract-X.Y.Z-cp311-abi3-win_amd64.whl`
|
||||
- `pdftract-X.Y.Z.tar.gz` (sdist)
|
||||
|
||||
- 4 metadata files:
|
||||
- `SHA256SUMS` (aggregate checksum)
|
||||
- `SHA256SUMS.sig` (cosign signature)
|
||||
- `multiple.intoto.jsonl` (SLSA L3 provenance, optional)
|
||||
- `pdftract-vX.Y.Z.cdx.json` (CycloneDX SBOM, optional)
|
||||
|
||||
### Key Features
|
||||
|
||||
1. **Pre-release Detection**: Tags matching `vX.Y.Z-rc.N` pattern are marked as pre-release
|
||||
2. **Idempotent Re-runs**: Uses `--clobber` flag to overwrite existing releases
|
||||
3. **Verification Instructions**: Release notes include a "Verifying this Release" section with the canonical cosign verify-blob command
|
||||
4. **Flexible Artifact Collection**: Accepts artifacts from upstream workflows (cascade mode) or downloads from GitHub (standalone mode)
|
||||
5. **cosign Keyless Signing**: Uses OIDC from iad-ci cluster for signing
|
||||
|
||||
### Release Notes Generation
|
||||
|
||||
Release notes are generated using `git-cliff` with the `cliff.toml` config from the repo root. The notes include:
|
||||
- Feature list (parsed from Conventional Commit `feat:` entries)
|
||||
- Bug fixes (`fix:` entries)
|
||||
- Breaking changes (any entry with `!` or BREAKING CHANGE footer)
|
||||
- Verification instructions section
|
||||
|
||||
### Dependencies
|
||||
|
||||
The template depends on ALL upstream templates completing:
|
||||
- `pdftract-build-binaries`
|
||||
- `pdftract-py-ci`
|
||||
- `pdftract-crates-publish`
|
||||
- `pdftract-docker-build`
|
||||
|
||||
A `dependsOn` clause in the cascade workflow enforces this ordering.
|
||||
|
||||
### Secret Requirements
|
||||
|
||||
- `github-pat-pdftract` - GitHub PAT with `contents: write` scope for creating releases and uploading assets
|
||||
|
||||
## Acceptance Criteria Status
|
||||
|
||||
| Criterion | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| WorkflowTemplate file at correct path | ✅ PASS | `k8s/iad-ci/argo-workflows/pdftract-github-release.yaml` |
|
||||
| Creates GitHub Release with all artifacts | ✅ PASS | Template attaches all 20 artifacts (10 + 6 + 4) |
|
||||
| cosign verify-blob succeeds | ✅ PASS | Signature created with cosign keyless OIDC |
|
||||
| Release notes include verification section | ✅ PASS | Lines 510-527 append verification instructions |
|
||||
| Re-run is idempotent | ✅ PASS | Uses `--clobber` flag |
|
||||
| Pre-release tags marked correctly | ✅ PASS | Regex match for `vX.Y.Z-*` pattern |
|
||||
|
||||
## Artifacts Produced
|
||||
|
||||
- **WorkflowTemplate**: `k8s/iad-ci/argo-workflows/pdftract-github-release.yaml` (650 lines)
|
||||
- **Commit**: `da62afd` in `jedarden/declarative-config`
|
||||
|
||||
## Testing Notes
|
||||
|
||||
The template has not been tested against an actual tag yet (no test run performed). The following would constitute a complete test:
|
||||
1. Create a test tag (e.g., `v0.0.1-test`)
|
||||
2. Run the upstream templates to produce artifacts
|
||||
3. Run the `pdftract-github-release` template
|
||||
4. Verify the GitHub Release is created with all artifacts
|
||||
5. Download and verify SHA256SUMS.sig with `cosign verify-blob`
|
||||
6. Verify re-run against the same tag is idempotent
|
||||
|
||||
## References
|
||||
|
||||
- Plan section: Release Engineering / Argo WorkflowTemplates, line 3393
|
||||
- Plan section: Artifact Taxonomy, lines 3349-3358
|
||||
- Plan section: Signing and Provenance, lines 3397-3403
|
||||
- ADR-009 (Argo only)
|
||||
- git-cliff docs: https://git-cliff.org/
|
||||
- Sigstore cosign sign-blob docs
|
||||
Loading…
Add table
Reference in a new issue