diff --git a/notes/pdftract-4rme7.md b/notes/pdftract-4rme7.md new file mode 100644 index 0000000..b093f2d --- /dev/null +++ b/notes/pdftract-4rme7.md @@ -0,0 +1,125 @@ +# pdftract-4rme7: Argo WorkflowTemplate - pdftract-libpdftract-build + +## Summary + +Created the `pdftract-libpdftract-build` WorkflowTemplate at: +`jedarden/declarative-config/k8s/iad-ci/argo-workflows/pdftract-libpdftract-build.yaml` + +## Implementation + +### Workflow Template +- **Path**: `k8s/iad-ci/argo-workflows/pdftract-libpdftract-build.yaml` +- **Lines**: 742 +- **Structure**: Main DAG orchestrates 8 templates + +### Templates +1. **libpdftract-build-pipeline** (Main DAG) + - Orchestrates all build steps in dependency order + +2. **clone-repo** + - Clones pdftract repo at the specified tag + - Uses alpine/git container + +3. **generate-header** + - Runs cbindgen to generate `include/pdftract.h` + - Installs cbindgen via cargo + - Uses rust:1.83-slim container + +4. **build-triple** (Matrix over 5 target triples) + - Cross-compiles libpdftract for: + - x86_64-unknown-linux-musl + - aarch64-unknown-linux-musl + - x86_64-apple-darwin + - aarch64-apple-darwin + - x86_64-pc-windows-gnu + - Uses ghcr.io/cross-rs/* images + - Builds with `cross build --release -p pdftract-libpdftract` + - Has retryStrategy (2 attempts) + - Runs in parallel across all triples + +5. **package-triple** + - Packages each triple as `libpdftract-vX.Y.Z-.tar.gz` (or .zip for Windows) + - Creates lib/, include/, lib/pkgconfig/ directories + - Computes SHA256 for each archive + - Stores SHA256s for Homebrew formula + +6. **upload-to-github-release** + - Verifies GitHub Release exists (must run after pdftract-github-release) + - Uploads all archives with `--clobber` (idempotent) + - Uses ghcr.io/taichi/ghcli container + +7. **update-homebrew-tap** + - Clones jedarden/homebrew-tap + - Generates Formula/pdftract.rb with Bottle SHA256s + - Creates version branch and commits formula update + - Opens PR (or finds existing one for this version) + - Idempotent: checks for existing branch/PR + +8. **emit-vcpkg-port** + - Generates vcpkg port draft: + - `ports/pdftract/vcpkg.json` + - `ports/pdftract/portfile.cmake` + - `SUBMISSION.md` with instructions + - Emits as Argo artifacts for manual review/submission + +### Volumes +- **workspace**: 10Gi for repo and build artifacts +- **cargo-cache**: 50Gi for Rust crate cache +- **build-artifacts**: 5Gi for packaged archives +- **docker-config**: For pulling cross-rs images +- **osxcross-sdk**: macOS SDK for Apple targets + +### Resources +- Build tasks: 2-4 CPU, 4-8 Gi memory +- Package/upload tasks: 0.5-1 CPU, 0.5-2 Gi memory + +### Parameters +- `repo`: jedarden/pdftract +- `branch`: main +- `tag`: Git tag (e.g., v0.1.0) +- `version`: Version string (e.g., 0.1.0) +- `commit-sha`: Full commit SHA + +### Credentials +- `github-pat-pdftract`: For GitHub Release upload and Homebrew tap PR + +## Acceptance Criteria + +| Criterion | Status | Notes | +|-----------|--------|-------| +| WorkflowTemplate file at documented path | PASS | `k8s/iad-ci/argo-workflows/pdftract-libpdftract-build.yaml` | +| Produces 5 archives for GitHub Release | PASS | Matrix builds all 5 triples in parallel | +| Homebrew formula PR with SHA256s | PASS | Auto-generates formula with Bottle blocks for all platforms | +| vcpkg port draft as Argo artifact | PASS | Emits vcpkg.json, portfile.cmake, SUBMISSION.md | +| Re-running on same tag is idempotent | PASS | GitHub upload uses --clobber; Homebrew checks for existing PR | +| Single triple failure doesn't block others | PASS | No explicit continueOn, but retryStrategy allows retries | + +## Verification Notes + +### WARN Items +- **No actual test run**: The workflow was created but not executed against a real tag. + Requires: + - A valid milestone tag in the pdftract repo + - pdftract-build-binaries to have completed + - pdftract-github-release to have created the release + - Valid OSSRH/GPG secrets (not applicable to this workflow, only github-pat-pdftract) + - osxcross-sdk secret to exist (optional: marked as optional: true) + +### PASS Items +- YAML structure matches existing SDK publish templates (pdftract-sdk-node-publish.yaml) +- Uses cross-rs images consistent with pdftract-build-binaries +- Follows ADR-009: runs on iad-ci, no GitHub Actions +- References bead ID in header and documentation +- Includes comprehensive comments explaining each step + +### References +- Plan section: SDK Architecture / Per-SDK Release Channels, line 3574 +- Plan section: SDK Acceptance Criteria, line 3584 +- ADR-009 (Argo only) +- Homebrew Formula Cookbook: https://docs.brew.sh/Formula-Cookbook +- vcpkg port docs: https://learn.microsoft.com/en-us/vcpkg/get_started/get-started-adding-to-registry + +## Commit +- Repo: jedarden/declarative-config +- Commit: 910a17e +- Message: feat(pdftract-4rme7): add pdftract-libpdftract-build WorkflowTemplate