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
6 changes: 4 additions & 2 deletions .github/PAGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,10 @@ the build installs it at `zig-out/docs-site`. `scripts/check_docs.py` runs befor

## Publishing contract

`.github/workflows/docs.yml` builds and uploads an ordinary artifact on `main` pushes, pull requests,
and manual runs. That job needs no Pages configuration or secrets, so it remains usable in forks.
`.github/workflows/ci.yml` builds and uploads an ordinary artifact in its Linux ReleaseSafe quality
job on `main` pushes, pull requests, and manual runs. That job needs no Pages configuration or
secrets, so it remains usable in forks. The same artifact must pass the Debug compatibility matrix
on Linux, Windows, and macOS before deployment.

Deployment runs only for a push to `main` in `LukasNiessen/ArchUnitZig`. The deploy job downloads the
already-validated ordinary artifact, configures Pages, packages the Pages artifact, and deploys it
Expand Down
140 changes: 140 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
name: CI

on:
push:
branches:
- main
pull_request:
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

env:
ZIG_VERSION: "0.16.0"
PYTHON_VERSION: "3.13"

jobs:
compatibility:
name: Debug · ${{ matrix.name }}
runs-on: ${{ matrix.os }}
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- name: Linux
os: ubuntu-latest
- name: Windows
os: windows-latest
- name: macOS
os: macos-latest
steps:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: ${{ env.PYTHON_VERSION }}

- name: Test pinned toolchain installer
run: python -B -m unittest scripts.test_install_zig

- name: Install checksum-pinned Zig
run: >-
python -B scripts/install_zig.py
--version "${{ env.ZIG_VERSION }}"
--destination "${{ runner.temp }}/zig-${{ env.ZIG_VERSION }}"

- name: Verify Zig version
run: zig version

- name: Run unit, acceptance, dogfood, and consumer tests
run: zig build test -Doptimize=Debug

quality:
name: ReleaseSafe, formatting, and docs · Linux
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: ${{ env.PYTHON_VERSION }}

- name: Test pinned toolchain installer
run: python -B -m unittest scripts.test_install_zig

- name: Validate pinned CI contract
run: python -B scripts/check_ci.py

- name: Install checksum-pinned Zig
run: >-
python -B scripts/install_zig.py
--version "${{ env.ZIG_VERSION }}"
--destination "${{ runner.temp }}/zig-${{ env.ZIG_VERSION }}"

- name: Verify Zig version
run: zig version

- name: Check Zig formatting
run: >-
zig fmt --check
build.zig build.zig.zon src
test/acceptance.zig test/dogfood.zig test/readme.zig test/readme

- name: Run ReleaseSafe unit, acceptance, dogfood, and consumer tests
run: zig build test -Doptimize=ReleaseSafe

- name: Build and validate ReleaseSafe guide and API docs
run: zig build docs -Doptimize=ReleaseSafe

- name: Upload validated documentation site
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: documentation-site
path: zig-out/docs-site
if-no-files-found: error
include-hidden-files: true
retention-days: 7

deploy:
name: Deploy GitHub Pages
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'LukasNiessen/ArchUnitZig'
needs:
- compatibility
- quality
runs-on: ubuntu-latest
permissions:
contents: read
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Download validated site
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
name: documentation-site
path: _site

- name: Configure Pages
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

- name: Package Pages artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: _site

- name: Deploy Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
76 changes: 0 additions & 76 deletions .github/workflows/docs.yml

This file was deleted.

22 changes: 22 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,15 @@ the repository documentation records decisions that outlive an individual ticket
zig build test
```

Documentation, public API, CI installer, and release-oriented changes also run:

```console
python -B -m unittest scripts.test_install_zig
python -B scripts/check_ci.py
zig build test -Doptimize=ReleaseSafe
zig build docs -Doptimize=ReleaseSafe
```

5. Open a pull request that links the issue, explains Zig-specific trade-offs, and records the exact
checks run.
6. Review the complete diff and checks, merge the pull request, delete the branch, and return to a
Expand Down Expand Up @@ -51,3 +60,16 @@ README/license root commit is the one unavoidable exception to the pull-request
- [ ] `zig fmt --check` passes.
- [ ] `zig build test` passes.
- [ ] Documentation and decisions match the implementation.

## Continuous integration

CI runs Debug tests on current GitHub-hosted Linux, Windows, and macOS runners. A Linux quality job
checks formatting, reruns the complete suite in `ReleaseSafe`, builds the documentation site and Zig
API docs, and uploads the validated artifact. The complete test command includes unit tests,
acceptance fixtures, executable dogfood rules, and the standalone README consumer.

Zig 0.16.0 is installed by `scripts/install_zig.py` from exact official archive URLs. The script
checks both the published byte size and SHA-256 before extraction. External workflow actions are
pinned to immutable commits with their reviewed release tag in a comment. CI deliberately uses no
dependency or build cache; adding one requires a key containing the Zig version and all relevant ZON
hash/lock inputs.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# ArchUnitZig

[![CI](https://github.com/LukasNiessen/ArchUnitZig/actions/workflows/ci.yml/badge.svg)](https://github.com/LukasNiessen/ArchUnitZig/actions/workflows/ci.yml)

ArchUnitZig turns a Zig project into a dependency graph and lets you enforce architecture as
ordinary `zig test` tests. Rules are lazy values: constructing a fluent chain performs no I/O;
checking it returns structured violations or integrates with Zig's test runner.
Expand Down
29 changes: 29 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1183,3 +1183,32 @@ duplicate branch-push and pull-request pair.
Consequence: guide prose, public Zig examples, generated API documentation, site navigation, and
deployment packaging fail one local/CI contract when they drift; the site stays maintainable and
offline-readable; and a fork can prove documentation quality without being able to publish it.

### D049 — CI verifies pinned binaries across three operating systems

The supported CI toolchain is exactly Zig 0.16.0, downloaded from the versioned official Zig release
URLs rather than a moving master build or an opaque setup action. A repository-owned standard-library
Python installer maps the hosted runner's operating system and architecture to a closed manifest of
Linux, macOS, and Windows archives. Every entry records the official byte size and SHA-256. Both are
verified before a path-traversal-checked ZIP or TAR extraction, the installed binary must report the
requested exact version, and unsupported versions or platforms fail closed. Unit tests exercise the
manifest, verification, and extraction boundary without network access.

All external GitHub Actions references use immutable commit SHAs with the reviewed stable release tag
beside them. The workflow grants only `contents: read` globally. Pages write and OIDC permissions
exist only on the canonical main-push deploy job, which depends on every compatibility and quality
gate. Fork pull requests can build and upload the ordinary documentation artifact but cannot deploy.
No dependency or build cache is configured; a future cache must include the Zig version plus relevant
ZON hash or lock inputs in its key.

Debug compatibility runs on current GitHub-hosted Linux, Windows, and macOS with `fail-fast` disabled,
so one platform cannot conceal another platform's result. The Linux quality job explicitly checks
formatting, runs the complete unit/acceptance/dogfood/README-consumer chain in `ReleaseSafe`, builds
and validates the guide plus compiler API docs, and uploads their deployable artifact. CI runs for
every pull request, manual dispatch, and `main` push. Feature-branch pushes are represented by their
pull-request run, avoiding a canceled duplicate status set on the same commit. Superseded runs for
the same Git reference cancel through the workflow concurrency key.

Consequence: toolchain downloads are reproducible and tamper-evident, allocator and path behavior are
exercised on the three supported runner families, documentation cannot deploy ahead of code quality,
and no optional matrix leg or `continue-on-error` can turn a red supported platform into a green PR.
Loading