From 9c0a408c493a83ef9ebbce3c6b25c7eef911a6d1 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Tue, 3 Nov 2026 09:49:51 +0100 Subject: [PATCH] docs: record CI in ADR 0032 and mention it in README and agent rules Also update docs-as-code to reflect that the docs check now runs in CI. --- AGENTS.md | 1 + CLAUDE.md | 1 + README.md | 2 ++ docs/adr/0032-github-actions-ci.md | 33 ++++++++++++++++++++++++++++++ docs/adr/README.md | 1 + docs/docs-as-code.md | 6 +++--- 6 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 docs/adr/0032-github-actions-ci.md diff --git a/AGENTS.md b/AGENTS.md index 1759843..a0cc76f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,7 @@ docker/ reproducible release builds (build.sh + pinned Dockerfiles) - After fixing a finding: add the crashing input to `SeedCorpus` in the fuzz project's `Program.cs` and regenerate with `--make-seeds Corpus` - **GUI hot reload:** `dotnet watch --project src/App.Desktop` (on WSL2/WSLg the window shows on the Windows desktop, no graphics dependencies to install) - **CLI:** `dotnet run --project src/Cli -- ` (no args → usage) +- **CI** (`.github/workflows/ci.yml`, ADR 0032): on every push to `main` and every PR it runs the offline test suite on Ubuntu and Windows, a fuzz smoke per parser target, and `docs/check-docs.sh`. Keep `dotnet test tests/PalladiumWallet.Tests` green locally first; the Android head is deliberately not built in CI - **Release binaries (all 3 targets):** `./docker/build.sh [windows|linux|android|all]` — reproducible Docker builds (toolchain pinned in `docker/Dockerfile.*`, no SDK needed on host), artifacts in `dist/`, version taken from the App csproj (details in `docker/README.md`) - Single-file desktop publish needs `-p:IncludeNativeLibrariesForSelfExtract=true` or Avalonia's native libs (Skia/HarfBuzz/ANGLE) stay outside the exe and it silently fails to start - Android workload dictates the SDK API level — error XA5207 → bump `ANDROID_SDK_PLATFORM` in `Dockerfile.android` diff --git a/CLAUDE.md b/CLAUDE.md index f94c780..926a728 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -62,6 +62,7 @@ docker/ reproducible release builds (build.sh + pinned Dockerfiles) - After fixing a finding: add the crashing input to `SeedCorpus` in the fuzz project's `Program.cs` and regenerate with `--make-seeds Corpus` - **GUI hot reload:** `dotnet watch --project src/App.Desktop` (on WSL2/WSLg the window shows on the Windows desktop, no graphics dependencies to install) - **CLI:** `dotnet run --project src/Cli -- ` (no args → usage) +- **CI** (`.github/workflows/ci.yml`, ADR 0032): on every push to `main` and every PR it runs the offline test suite on Ubuntu and Windows, a fuzz smoke per parser target, and `docs/check-docs.sh`. Keep `dotnet test tests/PalladiumWallet.Tests` green locally first; the Android head is deliberately not built in CI - **Release binaries (all 3 targets):** `./docker/build.sh [windows|linux|android|all]` — reproducible Docker builds (toolchain pinned in `docker/Dockerfile.*`, no SDK needed on host), artifacts in `dist/`, version taken from the App csproj (details in `docker/README.md`) - Single-file desktop publish needs `-p:IncludeNativeLibrariesForSelfExtract=true` or Avalonia's native libs (Skia/HarfBuzz/ANGLE) stay outside the exe and it silently fails to start - Android workload dictates the SDK API level — error XA5207 → bump `ANDROID_SDK_PLATFORM` in `Dockerfile.android` diff --git a/README.md b/README.md index 91e4b50..c3dcf72 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,8 @@ or run it on an emulator (see *Android emulator (developer setup)*). Tests are the **primary verification layer** — the core logic and crypto run headless, without the GUI or a real network. +Every push to `main` and every pull request runs the offline suite on Ubuntu and Windows, plus a fuzz smoke and the docs checks, via GitHub Actions (`.github/workflows/ci.yml`). + Run the whole suite: ```bash dotnet test diff --git a/docs/adr/0032-github-actions-ci.md b/docs/adr/0032-github-actions-ci.md new file mode 100644 index 0000000..dacacbd --- /dev/null +++ b/docs/adr/0032-github-actions-ci.md @@ -0,0 +1,33 @@ +# 0032. Run tests, fuzz smoke and docs checks in GitHub Actions + +- **Status:** Accepted +- **Area:** Testing +- **Recorded:** 2026-11-03 + +## Context + +The suite (unit, property-based, fuzz-corpus replay, in-process fake-server tests) is the primary verification layer for a wallet where a regression can lose funds, but it only ran on a developer's machine. Nothing prevented a failing change, a broken docs index or a Windows-only break from reaching `main`. + +## Decision + +`.github/workflows/ci.yml` runs on every push to `main` and on every pull request, with read-only permissions and cancellation of superseded runs: + +- **test**: restore, build (Release) and `dotnet test` of `tests/PalladiumWallet.Tests` on `ubuntu-latest` and `windows-latest`, uploading the TRX and coverage results as artifacts. Only the test project and its references are built, because the Android head needs a workload and SDK that CI does not provision. +- **fuzz-smoke**: one job per parser target, running `--random 20000` mutations; any escaping exception fails the job. +- **docs**: `docs/check-docs.sh`. + +The pipeline is offline: `LiveServerTests` does nothing without `PALLADIUM_TEST_SERVERS`, so no third-party indexing server is contacted. Coverage-guided fuzzing (afl++) and release builds stay manual. + +## Consequences + +- A change that breaks tests on either OS, a fuzz contract or the docs checks is visible before merge. +- Release, Android and Docker builds are not exercised by CI yet. +- Action versions are pinned to major tags; moving to commit SHAs would harden the supply chain further. +- Runs consume hosted-runner minutes; the fuzz matrix is the cheapest place to cut if needed. + +## References + +- `.github/workflows/ci.yml` +- `docs/check-docs.sh` +- `tests/PalladiumWallet.Fuzz/Program.cs` +- Related: 0025, 0026, 0027 diff --git a/docs/adr/README.md b/docs/adr/README.md index a4c8e4d..63e506e 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -35,6 +35,7 @@ One ADR per feature or significant design decision. Format: `template.md`. Workf | 0029 | [Persistent Android release keystore kept out of git](0029-persistent-android-signing-keystore.md) | Distribution | Accepted | | 0030 | [Single-source versioning with a mandatory changelog entry](0030-single-source-versioning-and-changelog.md) | Distribution | Accepted | | 0031 | [Explicitly defer multisig, Lightning, Tor and hardware wallets](0031-defer-multisig-lightning-and-hardware-wallets.md) | Scope | Accepted | +| 0032 | [Run tests, fuzz smoke and docs checks in GitHub Actions](0032-github-actions-ci.md) | Testing | Accepted | ADRs `0002` onwards were written retroactively on 2026-11-03 from the code, comments and changelog. If one misstates the original reasoning, fix it in a pull request. diff --git a/docs/docs-as-code.md b/docs/docs-as-code.md index 5b083cb..3eac8a5 100644 --- a/docs/docs-as-code.md +++ b/docs/docs-as-code.md @@ -100,11 +100,11 @@ flowchart LR - Relative Markdown links in `docs/` resolve. - `CLAUDE.md` and `AGENTS.md` match apart from their header block. -It needs only `bash` and standard tools, so it runs on a developer machine and can -be wired into CI later (the repository has no CI workflow today). +It needs only `bash` and standard tools, so it runs on a developer machine and in CI +(the `docs` job in `.github/workflows/ci.yml`, see ADR 0032). ## Possible next steps (not in place yet) -- Run `docs/check-docs.sh` and a Markdown linter in a CI workflow on pull requests. +- Add a Markdown linter to the `docs` CI job. - Add a link checker for external URLs. - Publish `docs/` as a static site if the audience outgrows GitHub's renderer.