python-doxygen
Reference documentation for python-doxygen
Loading...
Searching...
No Matches
ADR-011: Produce development, ordinary, and minified artifacts

Date: 2026-09-14

Status

Accepted

Context

ADR-004 established one generated consumer artifact, dist/doxygen-python.awk, with comment-only provenance and semantic parity with maintained source. ADR-007 later made that exact artifact and its checksum the published release interface. The project now needs distinct development, ordinary, and minified forms of the same filter so consumers can choose between maximum inspectability, reduced comment volume, and minimum distribution size.

The requested artifact expansion changes the build and release contract. It also introduces a build-time dependency on awk-minifier, whose released bytes must be pinned and independently verifiable. These changes are consequential because downstream repositories may pin exact release asset names and digests, and because an additional source-to-source transformation creates another place where semantic drift could be introduced.

The existing project principles remain applicable: maintained source is the source of truth, generated state remains disposable, provenance must not alter AWK behavior, portable operation under mawk and GNU awk remains required, and generated bytes must be tested rather than assumed equivalent.

Decision Drivers

  • Preserve one maintained, fully documented AWK source file.
  • Provide a fully documented generated artifact for inspection and debugging.
  • Preserve the established doxygen-python.awk name as the ordinary default consumer artifact.
  • Provide a smaller minified artifact without maintaining separate minified source by hand.
  • Keep build provenance visible in every generated artifact.
  • Pin the exact minifier release used by the build.
  • Keep make build free of implicit network access.
  • Make the top-level build leave all six governed artifacts in dist/.
  • Exercise every generated executable artifact with the same semantic suite.
  • Exercise every generated release candidate through Doxygen before release.
  • Publish checksums for each published executable artifact.

Decision

The maintained source SHALL remain doxygen-python.awk.

The build SHALL produce three executable AWK artifacts:

dist/doxygen-python.dev.awk
dist/doxygen-python.awk
dist/doxygen-python.min.awk

Their roles SHALL be:

  1. doxygen-python.dev.awk is the development artifact. It contains the maintained filter body without documentation removal or minification, plus a generated provenance header.
  2. doxygen-python.awk is the ordinary consumer artifact. It preserves the established downstream filename while removing full-line comments from the maintained filter body. It retains a generated provenance header.
  3. doxygen-python.min.awk is the minified consumer artifact. Its transformed body is produced by the pinned awk-minifier release from the comment-stripped filter body. It retains a generated provenance header identifying the minifier version.

The generated provenance header SHALL be owned by the build and kept outside the body passed through comment stripping or minification. Every artifact SHALL retain the shebang, source identity, artifact role or transformation, project version, build date, and source commit as comments only. Generated provenance MUST NOT introduce executable AWK state.

awk-minifier SHALL be a build dependency declared in dependencies.txt and materialized beneath vendor/ by the repository's pinned bashdeps bootstrap. The dependency SHALL pin an exact released version, public release-asset URL, and SHA-256 digest. The initial governed version is awk-minifier v0.2.4.

make deps MAY use the network to synchronize build dependencies. make deps-check and make build SHALL NOT silently download, repair, or advance build dependencies. make build SHALL fail clearly when the prepared pinned minifier dependency is unavailable or invalid.

make all SHALL be the complete top-level build path. It MAY synchronize the pinned build dependency, SHALL build all three generated executable artifacts, SHALL run the TAP semantic regression suite against those generated artifacts, and SHALL produce the three corresponding SHA-256 files. A successful make all therefore leaves all six governed build artifacts in dist/. This top-level orchestration does not weaken the requirement that make build itself remain offline and consume only prepared dependency state.

The semantic regression harness SHALL run against maintained source and all three generated artifacts. The combined test entry point SHALL emit one TAP-compliant stream so source/artifact parity is machine-consumable without concatenating independent TAP documents. Pull-request CI SHALL retain both mawk and GNU awk coverage.

Doxygen integration validation SHALL exercise all three generated artifacts when validating release candidates. A generated variant SHALL NOT be released merely because the maintained source passes the integration fixture.

make checksums SHALL produce:

dist/doxygen-python.dev.awk.sha256
dist/doxygen-python.awk.sha256
dist/doxygen-python.min.awk.sha256

Semantic-version releases SHALL publish all six generated files. The ordinary doxygen-python.awk asset remains the default compatibility path for downstream consumers that do not need a different representation. Downstream projects MAY pin any one of the three executable assets by exact version, public release URL, and digest.

Alternatives Considered

Maintaining three independent source files was rejected because documentation removal and minification are mechanical representations of one implementation, not separate behavior. Multiple maintained implementations would create an avoidable synchronization and review burden.

Replacing the established doxygen-python.awk release asset with only a .dev.awk or .min.awk asset was rejected because existing downstream consumers may already depend on the ordinary filename. The established name therefore remains the default consumer contract.

Allowing make build to download awk-minifier automatically was rejected because builds should be reproducible from explicitly prepared dependency state and should not hide network access. Dependency synchronization remains an explicit operation.

Tracking generated distribution artifacts in Git was rejected because generated bytes are reproducible build state and are already governed as disposable.

Stripping provenance before publication was rejected because exact generated bytes need an inspectable connection to source revision, project version, build date, and transformation. Instead, provenance is generated separately from the body transformation so it survives every representation.

Testing only the ordinary artifact was rejected because comment stripping and minification are distinct transformations. Each executable result must earn the same semantic and Doxygen confidence as the maintained source.

Publishing only the three executable artifacts without their individual checksums was rejected because downstream pinning relies on digest verification of exact release bytes.

Requiring callers of the top-level build to remember separate build, test, and checksum commands was rejected because the requested build contract is six artifacts whose executable forms have already passed semantic validation.

Consequences

The repository now has six generated release files instead of two. Release workflow, documentation, and downstream examples must therefore distinguish the three executable representations and their checksums.

A prepared build environment now requires the pinned awk-minifier asset in addition to the maintained source tree. That dependency is explicit, versioned, and digest-verified rather than discovered dynamically.

make all is intentionally broader than the offline make build primitive: it may prepare the pinned dependency, validates all generated executable forms, and creates their checksums. Local callers therefore have one top-level command that leaves the complete six-file build result behind.

Build and release validation become stronger because both transformations are covered by the same semantic suite and Doxygen integration contract. A defect in comment stripping or minification can therefore fail CI or release validation before publication.

The ordinary doxygen-python.awk filename remains stable, limiting migration impact for current consumers. Consumers that value source comments can select the development artifact; consumers that value size can select the minified artifact.

Future changes to artifact roles, filenames, provenance layout, minifier trust boundary, checksum format, or the set of published release assets are compatibility decisions and require corresponding ADR review.

Supersession

This ADR supersedes ADR-004 where ADR-004 defines a single generated artifact and single checksum. ADR-004 remains authoritative for the maintained-source boundary, generated-state model, comment-only provenance principle, and semantic parity requirement except where this ADR expands those concepts to three artifacts.

This ADR supersedes ADR-007 where ADR-007 defines exactly two published release assets. ADR-007 remains authoritative for exact-byte release validation, versioned downstream pinning, public retrieval, checksum verification, and release-artifact canary principles except where this ADR expands the publication set to six files.

Related Decisions

  • ADR-000 requires capability and release claims to match evidence.
  • ADR-004 established the maintained-source/generated-artifact boundary.
  • ADR-005 requires behavior-focused source/artifact parity testing.
  • ADR-006 governs the shared Make, dependency, test, and documentation infrastructure.
  • ADR-007 governs exact release publication and downstream pinning.
  • ADR-008 supplements focused fixtures with larger scenario regressions.