|
python-doxygen
Reference documentation for python-doxygen
|
Accepted
ADR-011 supersedes this ADR where it defines exactly one executable release artifact and one checksum. ADR-011 expands the publication set to development, ordinary, and minified executable artifacts with individual checksums. This ADR remains authoritative for exact-byte release validation, versioned downstream pinning, public retrieval, checksum verification, and release-artifact canary principles except where ADR-011 explicitly expands the asset set.
ADR-004 established dist/doxygen-python.awk and its SHA-256 checksum as the consumer-artifact boundary while deliberately deferring release publication from milestone 1. The sibling awk-doxygen and bash-doxygen projects validate maintained source, build the exact distribution artifact, verify its checksum, and attach both files to semantic-versioned GitHub releases.
Those published release assets are consumed by other repositories through bashdeps. A consuming repository pins a specific dependency version in its manifest, together with the public release-asset URL and expected SHA-256 digest. During that repository's build, bashdeps downloads those exact released bytes and verifies the digest before use. The consumer does not discover a moving version and does not require GitHub authentication to retrieve public release assets.
The user has directed python-doxygen to retain as much applicable project structure as practical from those sibling repositories. Release publication is therefore part of the repository's downstream dependency contract and must be governed explicitly.
bashdeps during downstream builds.The versioning workflow SHALL validate maintained source and the generated consumer artifact before creating a release. It SHALL use the root Make targets rather than duplicating build logic in workflow YAML.
For each release, the workflow SHALL:
dist/doxygen-python.awk with the calculated version supplied as build provenance;dist/doxygen-python.awk.sha256 from that exact artifact;dist/doxygen-python.awk and dist/doxygen-python.awk.sha256 to the GitHub release.The published asset names SHALL remain:
A downstream bashdeps manifest SHALL pin a specific released version rather than a branch, moving alias, or dynamically discovered latest version. The manifest entry SHALL identify the public release-asset URL and the expected SHA-256 digest. Retrieval of those public assets is intentionally independent of GitHub credentials.
A release-artifact canary MAY independently download those exact public assets, verify the checksum, and run the Doxygen integration fixture with the downloaded filter. Such a canary validates publication packaging; it is not part of the downstream dependency-resolution mechanism.
The released filter SHALL be staged in disposable generated state and SHALL NOT replace any stable documentation dependency declared in dependencies-docs.txt. A successful release canary SHALL NOT automatically advance dependency pins or make unrelated repository changes.
This decision supersedes only ADR-004's milestone-1 statement that release publication is outside scope. ADR-004's maintained-source name, generated artifact name, checksum name, comment-only provenance requirement, and source/dist parity requirements remain governing subject to ADR-011's later expansion of the generated artifact and checksum set.
Continuing to create releases without attaching the generated filter was rejected because the repository already defines a distinct consumer artifact and checksum. A release that omits those files would create a version tag without publishing the dependency bytes downstream repositories are expected to pin.
Publishing maintained doxygen-python.awk directly was rejected because it would bypass the generated provenance boundary established by ADR-004.
Having downstream repositories fetch main, another moving ref, or an unversioned URL was rejected because it would make builds non-reproducible and would defeat the manifest pinning model used by bashdeps.
Requiring GitHub authentication for downstream retrieval was rejected because the release assets are public and the sibling dependency model intentionally uses ordinary public release URLs plus digest verification.
Automatically updating stable dependency pins after each release was rejected because dependency advancement is a separate reviewed repository decision.
Release creation now depends on the same Make build and semantic test path used locally and in pull-request CI. Consumers receive one executable AWK artifact and one checksum file whose bytes have been tested together, subject to ADR-011's later expansion to three executable representations and their checksums.
Downstream repositories can pin an exact semantic version in their bashdeps manifest and reproduce the same dependency bytes later using only the public release URL and committed digest.
The release workflow has a stronger failure boundary: a semantic failure, build failure, checksum failure, or asset-publication problem prevents or exposes an invalid release rather than leaving the discrepancy for consumers to discover.
Future changes to asset names, provenance fields, checksum format, or the release-publication path are compatibility decisions and require corresponding ADR review.