Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 21 additions & 15 deletions .github/workflows/documentation-canary.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ jobs:
- name: Verify generated documentation state
run: |
test -f doc/adr/README.md
grep -F 'ADR-007' doc/adr/README.md
grep -F 'ADR-011' doc/adr/README.md
git check-ignore -q doc/adr/README.md
test -z "$(git status --porcelain --untracked-files=all -- doc/adr/README.md)"
test -f doc/reference/index.html
Expand All @@ -67,29 +67,35 @@ jobs:
sudo apt-get update
sudo apt-get install --yes curl doxygen make mawk

- name: Download exact released Python filter and checksum
- name: Download exact released Python artifacts and checksums
env:
RELEASE_TAG: ${{ github.event.release.tag_name }}
REPOSITORY: ${{ github.repository }}
run: |
mkdir -p .release-canary
base="https://github.com/${REPOSITORY}/releases/download/${RELEASE_TAG}"
curl --fail --location --silent --show-error \
--retry 5 --retry-all-errors --retry-delay 2 \
"${base}/doxygen-python.awk" \
--output .release-canary/doxygen-python.awk
curl --fail --location --silent --show-error \
--retry 5 --retry-all-errors --retry-delay 2 \
"${base}/doxygen-python.awk.sha256" \
--output .release-canary/doxygen-python.awk.sha256
for artifact in doxygen-python.dev.awk doxygen-python.awk doxygen-python.min.awk; do
curl --fail --location --silent --show-error \
--retry 5 --retry-all-errors --retry-delay 2 \
"${base}/${artifact}" \
--output ".release-canary/${artifact}"
curl --fail --location --silent --show-error \
--retry 5 --retry-all-errors --retry-delay 2 \
"${base}/${artifact}.sha256" \
--output ".release-canary/${artifact}.sha256"
done

- name: Verify released Python filter bytes
- name: Verify released Python artifact bytes
run: |
cd .release-canary
sha256sum -c doxygen-python.dev.awk.sha256
sha256sum -c doxygen-python.awk.sha256
sha256sum -c doxygen-python.min.awk.sha256

- name: Exercise exact released Python filter through Doxygen
- name: Exercise exact released Python artifacts through Doxygen
run: |
make test-doxygen \
AWK_BIN=mawk \
DOXYGEN_PYTHON_FILTER=.release-canary/doxygen-python.awk
for artifact in doxygen-python.dev.awk doxygen-python.awk doxygen-python.min.awk; do
make test-doxygen \
AWK_BIN=mawk \
DOXYGEN_PYTHON_FILTER=".release-canary/${artifact}"
done
20 changes: 15 additions & 5 deletions .github/workflows/semver.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ jobs:
sudo apt-get update
sudo apt-get install --yes doxygen mawk gawk

- name: Prepare pinned build dependencies
run: make deps

- name: calculate version
id: calculate-version
uses: bitshifted/git-auto-semver@c4e8f005e839f822325356f141939cf6c76b5701 # pin@v1
Expand All @@ -42,24 +45,27 @@ jobs:
- name: Validate maintained source
run: make check test-source AWK_BIN=mawk

- name: Build and validate release artifact
- name: Build and validate release artifacts
run: |
make test-dist \
AWK_BIN=mawk \
VERSION="${{ steps.calculate-version.outputs.version-string }}"

- name: Exercise release candidate through Doxygen
- name: Exercise release candidates through Doxygen
run: |
make test-doxygen \
make test-doxygen-dist \
AWK_BIN=mawk \
DOXYGEN_PYTHON_FILTER=dist/doxygen-python.awk
VERSION="${{ steps.calculate-version.outputs.version-string }}"

- name: Generate and verify release checksum
- name: Generate and verify release checksums
run: |
make checksums \
AWK_BIN=mawk \
VERSION="${{ steps.calculate-version.outputs.version-string }}"
cd dist
sha256sum -c doxygen-python.dev.awk.sha256
sha256sum -c doxygen-python.awk.sha256
sha256sum -c doxygen-python.min.awk.sha256

- name: Generate release notes
id: release-notes
Expand All @@ -79,5 +85,9 @@ jobs:
draft: false
prerelease: false
files: |
dist/doxygen-python.dev.awk
dist/doxygen-python.dev.awk.sha256
dist/doxygen-python.awk
dist/doxygen-python.awk.sha256
dist/doxygen-python.min.awk
dist/doxygen-python.min.awk.sha256
19 changes: 15 additions & 4 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,22 +22,33 @@ jobs:
semantic:
runs-on: ubuntu-24.04
strategy:
fail-fast: false
matrix:
awk: [mawk, gawk]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install AWK implementation
run: sudo apt-get update && sudo apt-get install -y ${{ matrix.awk }}
- name: Run source and dist semantic suite
run: make test AWK_BIN=${{ matrix.awk }}
- name: Verify checksum generation
run: make checksums AWK_BIN=${{ matrix.awk }}
- name: Run complete build and generated-artifact suite
run: make all AWK_BIN=${{ matrix.awk }}
- name: Run maintained-source semantic suite
run: make test-source AWK_BIN=${{ matrix.awk }}
- name: Verify generated checksums
run: |
cd dist
sha256sum -c doxygen-python.dev.awk.sha256
sha256sum -c doxygen-python.awk.sha256
sha256sum -c doxygen-python.min.awk.sha256

doxygen:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install integration dependencies
run: sudo apt-get update && sudo apt-get install -y doxygen mawk
- name: Prepare pinned build dependencies
run: make deps
- name: Exercise maintained filter through Doxygen
run: make test-doxygen AWK_BIN=mawk
- name: Exercise generated artifacts through Doxygen
run: make test-doxygen-dist AWK_BIN=mawk
65 changes: 45 additions & 20 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,44 +54,69 @@ at least `mawk` and GNU awk.

Behavior-focused fixtures live under `tests/python/`. Fixtures protect public
behavior, not helper structure. The same semantic suite must run against
maintained `doxygen-python.awk` and generated `dist/doxygen-python.awk`.
maintained `doxygen-python.awk` and all generated executable artifacts:
`dist/doxygen-python.dev.awk`, `dist/doxygen-python.awk`, and
`dist/doxygen-python.min.awk`.

Run `make check` to apply GNU awk fatal linting to maintained root AWK sources.
Linting remains intentionally separate from semantic testing. Use
`make test AWK_BIN=mawk` and `make test AWK_BIN=gawk`; the test harness emits one
TAP-compliant stream across all selected filter variants. Preserve source-line
correspondence where practical, and pass ordinary Python source outside translated
docstrings through unchanged. `make test-doxygen` exercises the selected Python
filter against the focused Python/Doxygen integration fixture.
Linting remains intentionally separate from semantic testing. After preparing
build dependencies with `make deps`, use `make test AWK_BIN=mawk` and
`make test AWK_BIN=gawk`; the test harness emits one TAP-compliant stream across
all selected filter variants. Preserve source-line correspondence where
practical, and pass ordinary Python source outside translated docstrings through
unchanged. `make test-doxygen` exercises one selected Python filter, while
`make test-doxygen-dist` exercises all generated release candidates.

## Build Dependencies

Build dependencies are pinned in `dependencies.txt` and materialized beneath
`vendor/` by the SHA-256-pinned `bashdeps` bootstrap. ADR-011 requires an exact,
digest-verified `awk-minifier` release for minified artifact generation.

`make deps` may use the network. `make deps-check` and `make build` consume
prepared state without silently downloading, repairing, or advancing pins. The
canonical build must fail clearly if its prepared minifier dependency is missing
or invalid.

## Documentation Tooling

Project reference documentation describes this repository's maintained AWK,
Bash, Markdown, and ADR sources. It is distinct from the Python-filter integration
test.

Documentation-only dependencies are pinned in `dependencies-docs.txt` and are
materialized beneath `vendor/` by the SHA-256-pinned `bashdeps` bootstrap. The
set includes released `awk-doxygen`, released `bash-doxygen`, and released
Documentation-only dependencies are pinned separately in `dependencies-docs.txt`
and are materialized beneath `vendor/` by the same pinned `bashdeps` bootstrap.
The set includes released `awk-doxygen`, released `bash-doxygen`, and released
`adrctl`. `make deps-docs` may use the network; `make deps-docs-check`,
`make adr-index`, and `make docs` consume prepared state without silently
repairing or advancing dependency pins.

Generated `doc/adr/README.md`, `doc/reference/`, and `vendor/` state is disposable
and must remain ignored by Git.
Generated `doc/adr/README.md`, `doc/reference/`, `dist/`, and `vendor/` state is
disposable and must remain ignored by Git.

## Build and Release

The maintained source and consumer outputs are `doxygen-python.awk`,
`dist/doxygen-python.awk`, and `dist/doxygen-python.awk.sha256`. `make build` is
the canonical artifact build. Build provenance is comments only and must not add
executable AWK state.
The maintained source is `doxygen-python.awk`. ADR-011 governs three generated
executable representations: `dist/doxygen-python.dev.awk` preserves the documented
body, `dist/doxygen-python.awk` removes full-line comments while retaining the
established default consumer filename, and `dist/doxygen-python.min.awk` is
produced by the pinned minifier. `make checksums` produces one SHA-256 file for
each executable artifact.

`make all` is the complete top-level build path. It may synchronize the pinned
build dependency, then must build all three generated executable artifacts, run
the TAP semantic suite against those generated bytes, and leave all three
corresponding SHA-256 files in `dist/`. `make build` remains the canonical
offline artifact-generation step and must not acquire dependencies implicitly.
Generated provenance is owned by the build, remains comments only, and must be
kept outside body transformations so comment stripping or minification cannot
erase provenance or introduce executable AWK state.

Semantic-version releases are a downstream dependency interface. The versioning
workflow must validate maintained and generated bytes, verify the checksum, and
publish both `doxygen-python.awk` and `doxygen-python.awk.sha256` as release
assets. Other repositories may pin those exact release assets with `bashdeps`,
so a version tag without the governed assets is an incomplete release.
workflow must validate maintained and generated bytes, exercise all generated
variants through Doxygen, verify all three checksums, and publish all six governed
files. Other repositories may pin any exact released executable asset with
`bashdeps`; `doxygen-python.awk` remains the default compatibility path.

Exact published release bytes must be checksum-verified and exercised through the
Python/Doxygen integration fixture. Do not substitute a tag checkout for this
Expand Down
Loading
Loading