Repository navigation
Read and search the documentation at one address, moved on to each release once it is published - #439
Merged
Merged
Conversation
…lease once it is published The documentation is published as a website by isa-group/restest-site, built from a released version's files as they are. documentation-site.yml writes a published release's tag into the site's restest-version with a deploy key, never over a higher version, and waits until the site names it. DocumentationSiteTest holds every pull request to the shape of docs/ the site reads, and DocumentedLinksTest no longer accepts a link to a page's own title. ADR-0047 records the decision and amends ADR-0031; docs/ci.md says what to set up once and adds the step before every tag. The README and the skill give the site's address, and the first section of docs/README.md is named "Reference", its group on the site. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ssegura
added a commit
that referenced
this pull request
Nov 6, 2026
…n light and dark, with that run's report.json beside it (#440) **Related:** #439, the documentation site, whose first page will show this run; that page follows in `isa-group/restest-site`. ## What you can do now that you could not before Read in the manual what `report.html` looks like from a real run: chapter 4 now shows the top of the page, an operation opened at a fault, and what was found, in light and in dark, from the clinic as the Web Fuzzing Dataset builds it, tested for a minute by RESTest 2.4.0 with nothing but its document. The run's `report.json` is beside the pictures, so the chapter's `jq` questions can be tried without running anything, and the chapter gives the two commands that make such a run. The pictures are twice as sharp as before, 2560 pixels wide, and the README's two of the pet shop no longer say "2.2.0-SNAPSHOT". ## Try it yourself With Java and git, from a clean clone: ```bash git clone --branch feat/m12-7-clinic-run https://github.com/isa-group/RESTest.git restest-clinic-run cd restest-clinic-run ./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.DocumentedRunTest' \ -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Tests run:.*in io|BUILD' ``` ``` [INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.167 s -- in io.restest.arch.DocumentedRunTest [INFO] BUILD SUCCESS ``` Now keep the wrong run: one made by a snapshot build, with a picture missing. ```bash sed -i.bak 's/"version":"2.4.0"/"version":"2.5.0-SNAPSHOT"/' docs/manual/images/clinic-run/report.json rm docs/manual/images/clinic-run/report.json.bak docs/manual/images/clinic-run/fault-dark.png ./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.DocumentedRunTest' \ -Dsurefire.failIfNoSpecifiedTests=false | grep -A2 'Expecting empty' | head -3 ``` ``` Expecting empty but was: ["docs/manual/images/clinic-run/fault-dark.png is missing", "the run was made by 2.5.0-SNAPSHOT, which is not numbered as a release", "docs/manual/04-reading-what-a-run-says.md does not name RESTest 2.5.0-SNAPSHOT, the version that made the run it pictures"] ``` Undo it with `git checkout -- docs`. The pictures are best seen on GitHub, in [chapter 4 on this branch](https://github.com/isa-group/RESTest/blob/feat/m12-7-clinic-run/docs/manual/04-reading-what-a-run-says.md#the-page), which shows the dark ones with GitHub's dark theme; and, with `jq`, one question of the chapter, asked of the kept report: ```bash jq -c '.totals | {requests, errors, operationsWithErrors, warnings, operationsWithWarnings}' docs/manual/images/clinic-run/report.json ``` ``` {"requests":182898,"errors":26973,"operationsWithErrors":30,"warnings":71237,"operationsWithWarnings":39} ``` ## How it works The manual keeps one run of the clinic it uses throughout, as the Web Fuzzing Dataset builds it: an image for Apple silicon as well as Intel and AMD, `webfuzzing/wfd-petclinic-rest`, pinned by its digest, run with `restest run http://localhost:9967/petclinic/v3/api-docs` for the minute RESTest takes when no time is given, nothing else handed over. Its `report.json` and six pictures of its `report.html` live in `docs/manual/images/clinic-run/`; chapter 4 shows the pictures, each with its dark version, and gives the two commands. The documentation site's first page will show the same pictures, and take its figures and faults from that `report.json`, as the run RESTest makes with nothing to configure. A test, `DocumentedRunTest`, holds the kept run to being that run: written by a version numbered as a release, not cut short, given the default minute, with no plan, file of settings or list of values, every setting as shipped, the six pictures present as PNG files, and chapter 4 naming its version. A run that is not that one fails the build, saying what is wrong with it. A run of a version numbered as a release can only be made in the pull request that prepares the release, since every other build is a snapshot. So the release steps in `docs/ci.md` say to make the run and the pictures again there whenever `report.html` or the kinds of fault changed since the previous release (a `git diff --stat` of the two files tells), and how, by hand in Chrome at a device pixel ratio of 2; the guide to contributing asks a pull request that changes either to say so in its description. ## What changed in the code - `docs/manual/images/clinic-run/` (new) — the run's `report.json`, as RESTest 2.4.0 wrote it, and `summary-`, `fault-` and `found-`, each `-light.png` and `-dark.png`, 2560 pixels wide. They replace `docs/manual/images/the-page.png`, of another run, light only and half as wide. - `docs/manual/04-reading-what-a-run-says.md` — "The page" shows the three views with `<picture>` and a dark source, as the README already does, says how the run was made and gives its two commands; the `jq` section says where the kept report is and that the answers shown are of an earlier run. - `docs/images/petstore-report-{light,dark}.png` — taken again from the README's ten-second run of the pet shop with RESTest 2.4.0, at twice the width. - `restest-arch-tests/.../DocumentedRunTest.java` (new) — the checks above, as functions of a folder and of a report, with the repository's run and fourteen wrong ones: each kind of wrong report, a missing picture, a file that is no PNG, a missing or unreadable report, and a chapter naming another version. - `docs/ci.md` — release step 2 names the pictures and the `git diff` that says when; a section "The pictures of the report" says how to make them, with the image pinned; the table of gates lists the test. - `CONTRIBUTING.md` — one paragraph: a pull request that changes how `report.html` looks, or the kinds of fault, says so. - `docs/adr/0047-the-documentation-site.md` §3, `docs/DESIGN.md`, `AGENTS.md` — the folder the site will read, held by the test. ## Evidence - [x] Tests: one class added, `DocumentedRunTest`, with four tests (the kept run, a well-kept report, nine wrong reports, missing and broken files). `./mvnw verify`: all green, 161 architecture and documentation tests. — the checks of this pull request - [x] Architecture tests: 161, none weakened. - [x] Mutation score: not applicable; no oracle or constraint touched. - [x] Per-request overhead: not applicable; nothing a run does changes. - [x] Smoke run: not applicable. - [x] Idle time: not applicable. - [x] Artefact: the run itself, from its summary: 182898 requests to 43 operations in 1m 0s, 1% of it idle; 26973 errors on 30 operations and 71237 warnings on 39. The documentation site built from this branch shows the three views in chapter 4, following its theme. `report.json` is 2.0 MB on disk and about 145 KB as a git object; the six pictures 2.0 MB, the README's two 0.5 MB. ## Decisions taken - **One run, three views, light and dark, in the documentation** (maintainer), so that the manual, the README and the site's first page show the report from one place, always the latest, rather than the site keeping pictures of its own. - **The clinic as the Web Fuzzing Dataset builds it, natively** (maintainer). The image chapter 3 uses, `springcommunity/spring-petclinic-rest:4.0.2`, is built only for Intel and AMD; on Apple silicon it ran in emulation, answered 46,136 requests in the minute, and warmed up so slowly that the first half of the timeline was nearly empty. The dataset's build of the same API runs natively: 182,898 requests, a timeline full from its first seconds. It is pinned by digest in the chapter and the release steps, as chapter 3 pins its own clinic. - **Pictures at a device pixel ratio of 2** (maintainer), sharp on any screen; each remake costs about 2.5 MB of history rather than 0.8. - **Made again in the pull request that prepares a release, not in the one that changes the page.** The test requires a version numbered as a release, which only that pull request builds. The procedure is in `docs/ci.md`, beside the other release steps, rather than in the guide to contributing, which only asks for the change to be said. - **The test checks the version's form, not that it was published**, and that chapter 4 names it; the alt texts carry no counts and no operation name, so that they do not go stale when the run is made again. - **The default minute is written in the test**: if `--budget`'s default changes, the test fails until the run is made again with it, which is what it should do. - **The sentence a coding agent is given is not changed here**: it moves to a pull request of its own, merged with 2.5.0, since its new address, the site's page for coding agents, answers only once 2.5.0 is published. - Not taken from reviewers: - extending `DocumentedLinksTest` to the `src` and `srcset` of raw HTML, which would check the pictures' links on every page: ADR-0047 §3 leaves links in raw HTML to the site's own build, which runs before every tag; - making the run again at every release, with its version required to equal the release's: the run is made again when the page or the kinds of fault change, and the page names the version that made it; - regenerating the `jq` answers from the kept report: they stay those of an earlier run, and the chapter says so; - reading the default budget from the command line's help; - running the pictures through `pngquant`, about half their size, which is not installed here; - ADR-0047 is changed in place rather than amended: it was merged on 6 November, and no release carries it yet. ## Open questions None. The pull request that changes the sentence for coding agents touches the same row of `docs/ci.md`'s table of gates; whichever is merged second takes both additions. --- - [x] Targets `master` - [x] English throughout, including comments and test names - [x] The hard rules in `AGENTS.md` hold 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
10 tasks done
ssegura
added a commit
that referenced
this pull request
Nov 10, 2026
…n at one address (#442) **Related:** None. This is the release of 2.5.0, with what `master` holds on 10 November: #432 to #441. **This pull request is merged before the tag `v2.5.0`, which goes on its merge commit.** ## What you can do now that you could not before - **Get 2.5.0.** Once this is merged and tagged, it installs five ways: - `brew install isa-group/tap/restest`; - `jbang app install restest@https://isa-group.github.io/jbang-catalog/jbang-catalog.json`, new in this version, with no Java installed first; - `docker run ghcr.io/isa-group/restest:2.5.0`; - the release's archives, with Java alone; - or built from the source. - **What 2.5.0 adds:** - RESTest runs with jbang on macOS, Linux and Windows, which downloads a Java when there is none (#434); - every archive carries a skill that teaches a coding agent to use RESTest, `skills/restest/SKILL.md` (#437), and the page for coding agents gives the sentence to hand one, the same in the README (#441); - the documentation can be read and searched at one address, moved on to each release once it is published (#439); - installing takes a few lines, with the details in the manual (#435), and the README and the architecture's diagrams are simpler (#438); - the manual shows `report.html` as a real run of the clinic draws it, light and dark, with that run's `report.json` beside it (#440); - a fix: an API that answers in HTTP/1.0, as Python's `http.server` does, gets a reply read for every request (#436). - **What stays the same as in 2.4.0:** the command line, its exit codes, plans, dictionaries, settings and both reports. ## Try it yourself From a clean clone, with only Java and git: ```bash git clone --quiet --branch release/2.5.0 https://github.com/isa-group/RESTest.git restest-2.5.0 && cd restest-2.5.0 ./mvnw -q install -DskipTests ./restest version ./restest run restest-cli/src/test/resources/pet-shelter.yaml --url http://127.0.0.1:1 --budget 3s; echo "exit $?" ls restest-out grep -o '"verdict" *: *"[A-Za-z]*"' restest-out/report.json dist/assemble.sh ../release --archives > /dev/null && ls ../release tar -xzf ../release/restest-2.5.0.tgz -C ../release && ../release/restest-2.5.0/bin/restest version ls ../release/restest-2.5.0/skills/restest ``` Below is the real output, from a fresh clone of this branch on 10 November; the Java line will be your own. Nothing listens on port 1, so the run ends with `3`, and it still writes both files; the archive carries the skill: ``` RESTest 2.5.0 Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64 RESTest testing Pet Shelter at http://127.0.0.1:1 4 of 4 operations can be tested, seed 2125531189854063678, budget 3s what it sends depends on the API's own replies, so the seed alone does not repeat this run; --store keeps what it sent 64 requests to 4 operations in 361ms, 90% of it idle opening lap: 4 requests in 46ms, 0 of 4 operations answered 2xx 64 no reply 1 of them were pushing at the API with values nobody sensible would send 3 creation(s) meant to begin a series about a thing the run created were not accepted, so no series began no faults found report written to restest-out/report.json (9.6 KiB) page written to restest-out/report.html (90.7 KiB) the run itself was not kept; pass --store to keep every request and reply restest: nothing at http://127.0.0.1:1 answered any of the 64 requests, so the API was never actually tested. Check the address, and that it is running. exit 3 report.html report.json "verdict":"nothingAnswered" restest-2.5.0 restest-2.5.0.tgz restest-2.5.0.zip RESTest 2.5.0 Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64 SKILL.md ``` With Docker as well, the image is built from the same clone, as the release builds it: ```bash docker build --quiet --tag restest:2.5.0 . > /dev/null && docker run --rm restest:2.5.0 version ``` ``` RESTest 2.5.0 Java 21.0.13 (Eclipse Adoptium), Linux 7.0.14-linuxkit aarch64 ``` What the tag will leave on the Central Portal, laid out from the same clone: ```bash ./mvnw -q package -Pcentral -DskipTests -pl restest-cli -am && dist/central.sh target/central ls target/central/maven-central/es/us/isa/restest grep -c "<dependency>" target/central/maven-central/es/us/isa/restest/restest-cli/2.5.0/restest-cli-2.5.0.pom ls restest-cli/target/lib | wc -l ``` ``` /…/restest-2.5.0/target/central/maven-central restest-cli restest-core restest-exec restest-gen restest-oracles restest-report restest-spec restest-store 70 70 ``` ## How it works **The version.** `-SNAPSHOT` is how Maven writes "on the way to this version", and this pull request removes it from every `pom.xml`. After the merge, the tag `v2.5.0` on the merge commit starts the release workflow ([`docs/ci.md`](docs/ci.md#releases)): - it builds the image and the archives, and checks them on three operating systems and two processors; - it installs the Homebrew formula for the archive on macOS and Linux, and runs the jbang catalog for this version; - it signs the eight modules and uploads them to the Central Portal, once a maintainer approves the `central` job; the Portal validates them and publishes nothing; - it pushes the image, and leaves a draft release for a maintainer to write the notes in and publish. A maintainer publishes the deployment on the Portal before publishing the release. Publishing the release starts the Homebrew workflow, which writes 2.5.0 into the tap, the jbang workflow, which writes it into the catalog, and the documentation site's, which moves the site on to 2.5.0. Before the tag, the documentation site is built by hand from `master`, so that a tag the site cannot build is never pushed. **The base images.** Step 1 of every release moves the `Dockerfile`'s two base images to the newest patch; they are the newest already, so the `Dockerfile` does not change, nor the Java the image prints. **The pages.** The README and chapters 2 and 9 of the manual name the version to install, and now name 2.5.0. Every other page was written for 2.5.0 as each change landed, from #432 to #441. Those that give a minimum version (the skill's "2.4.0 or later"), speak of a past release, or name the version the manual's kept run was made with (chapter 4's, 2.4.0) stay as they are. ## What changed in the code No Java code changed, and nothing under `src/`. - **Version:** every `pom.xml`, from `2.5.0-SNAPSHOT` to `2.5.0`, ten files. The JSON Schemas' `$id` already names `v2.5.0` since #432. - **`README.md`:** the Docker command runs `2.5.0`. - **`docs/manual/02-installing.md`:** Homebrew's and jbang's `restest version`, Docker, the archive, the checksums, the source and Updating name 2.5.0. The Docker and archive outputs are those above, unchanged but for the version. Homebrew's and jbang's lines and sizes are what this pull request's [run of `release.yml`](https://github.com/isa-group/RESTest/actions/runs/42861198585) printed, as `docs/ci.md` asks: `check-homebrew` installed 628 MB on macOS and 824 MB on Ubuntu (625 and 823 before) and printed `Java 21.0.13.0.3 (Homebrew), Mac OS X 26.7.2 aarch64`; `check-jbang` started RESTest on Java 27.0.1.0.2, where the page said `27`, with 636 MB of Javas, where it said some 600. jbang's libraries, 37 MB, stay as they are: `check-jbang` counts the sources and the Javadoc Maven Central gets, which jbang does not download, and the published release's run of `jbang.yml` is what they are checked against. - **`docs/manual/09-exit-codes-and-ci.md`:** the workflow fetches and runs the 2.5.0 archive. ## Evidence - [x] **Tests:** `./mvnw verify` is green at `edfb1510`, with version 2.5.0: 4,981 tests, 0 failures, BUILD SUCCESS in 2 min 36 s. 162 of them are the architecture and documentation rules, `PublishedSchemasTest` among them, which on a release requires the schemas' `$id` to name it; they pass again with chapter 2's sizes. The first push's [Release](https://github.com/isa-group/RESTest/actions/runs/42861198585) run is green, `central` and `publish` skipped, as on every pull request. On the second push, [CI](https://github.com/isa-group/RESTest/actions/runs/42862469536)'s *Java 26 on ubuntu-latest* failed on its first attempt in `RunLoopTest.an_operation_told_to_wait_is_skipped`, which counted `getPet`'s wait twice where it expects once: a wait the API asks for that lasts past the end of the budget ends at the budget's end, and a request sent at that very moment is let through and refused again, beginning a second wait. The row passed when re-run, with the two rows the failure had cancelled, and every check is green. Nothing under `src/` changes here; the race is put right in a pull request of its own, after this release. - [x] **Architecture tests:** unchanged, none weakened. - [x] **Mutation score:** no oracle or constraint touched. - [x] **Per-request overhead:** unchanged; nothing under `src/` changed. - [x] **Smoke run:** unchanged, for the same reason; CI runs it on this pull request. - [x] **Idle time:** unchanged. - [x] **Artefact:** `check-restest.sh 2.5.0` passes on both the archive and the image built here, every check `ok`: `--launcher` on `restest-2.5.0/bin/restest`, and `--image restest:2.5.0`, built again without Docker's cache. `dist/central.sh` passes on the build above; `restest-cli`'s POM names the 70 libraries the archive's `lib/` carries beside `restest-cli` itself. ## Decisions taken - **The pictures of the report are not made again.** Neither `report.html` nor `FaultCategory.java` changed since v2.4.0, and #440, which added the manual's kept run, says they are made again only when the page or the kinds of fault change. Chapter 4 keeps naming 2.4.0, the version that run was made with. - **No release evaluation on the Web Fuzzing Dataset in this pull request.** 2.5.0 changes no request but HTTP/1.0 replies (#436), measured in its own pull request. The showcase campaign of 2.5.0, one minute per API on the dataset's 52 APIs, runs once the release is published. - **Guava is not moved in this release** (#430, Dependabot alert 48, raised in 2.4.0's release): the maintainer decided it waits. RESTest's own code uses neither Guava nor Java serialisation. - **The release notes are not in this pull request.** They go into the draft release after the tag, as `docs/ci.md` says. ## Open questions None. After the merge, each step taken by a maintainer: the documentation site built by hand from `master`; the tag `v2.5.0` on the merge commit, and the approval of the `central` job; the notes in the draft; the deployment published on the Central Portal, then the release; the installation commands tried from outside; and the pull request that moves `master` to `2.6.0-SNAPSHOT`. --- - [x] Targets `master` - [x] English throughout, including comments and test names - [x] The hard rules in `AGENTS.md` hold 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related: isa-group/restest-site#2, which publishes the documentation as a website, now live at https://isa-group.github.io/restest-site/docs/.
What you can do now that you could not before
Read and search RESTest's documentation at one address, https://isa-group.github.io/restest-site/docs/, which the README and the skill for coding agents now give. Once this is merged and its key is set up, publishing a release moves the site on to that release by itself and checks that it did; and a pull request that would leave the site unable to build — a page in no index, an index of another shape, a page with no title, a link to a page's own title — fails here, naming the file, rather than after the release.
Try it yourself
With Java and git, from a clean clone:
Now add a page that no index lists, and a link to a page's own title, which the site shows above the page rather than as a heading:
Undo it with
git checkout docs/faults.md && rm docs/faults-again.md. With Node 26, the site builds from this branch, and its first group is named "Reference":The workflow cannot be tried before it is on
masterand its key is set up (see "Open questions").How it works
The site lives in its own repository,
isa-group/restest-site. Before each build it takes RESTest at the release named in its one-line filerestest-versionand reads the Markdown underdocs/,README.md,AGENTS.mdandCONTRIBUTING.mdas they are; its menu comes from the two indexes, the manual's numbered list of chapters and one group per##section ofdocs/README.md. Nothing of the site is in RESTest's build. ADR-0047 says why it is done this way, and everything in the pages the site relies on.When a release is published, the new workflow
documentation-site.ymlwrites its tag into the site'srestest-versionwith a deploy key, ashomebrew.ymlandjbang.ymlwrite into the tap and the catalog: never over a higher version, and not again when it is there. That commit makes the site build from the new tag and publish it; the workflow then waits until the site'sllms.txtnames the version.A tag never changes, so a release whose pages the site cannot build would leave the site unable to publish anything until the site is changed. Two things keep that from happening:
DocumentationSiteTestholds every pull request to the rules the site builds by, and before a tag the site is built by hand frommaster(a new step in the release steps ofdocs/ci.md).What changed in the code
.github/workflows/documentation-site.yml— three jobs:versionchecks the tag and that it is a published release;push, in the environmentrestest-site, writes the tag into the site with the keyRESTEST_SITE_KEY, checking out nothing of RESTest while the key is loaded;check-publishedwaits up to fifteen minutes for the site to name the version. Started by a release's publication, or by hand with a tag. No pull-request trigger: it would test a regular expression and nothing of the writing.restest-arch-tests/.../DocumentationSiteTest.java— the site's rules as functions of a folder, applied to the repository and, with@TempDir, to a small documentation broken in 24 ways, each of which has to be reported. Two rules are stricter than the site: every chapter ofdocs/manual/is in the manual's list, and each item of that list starts with its link.DocumentedLinksTest.java— its link pattern, line reader and code-fence filter are shared with the new test; and a page's title, its first#heading, is no longer a heading a link may name, since the site shows the title above the page rather than as a heading.docs/adr/0047-the-documentation-site.md— the decision, what the site depends on, what only the site checks, and the alternatives;docs/adr/README.mdlists it, and ADR-0031, whose manual had one rendering, is amended.docs/ci.md— five workflows; a section on the documentation site with its jobs and what to set up once; the release step before the tag; three runs to see green after publishing; the test in the table of gates.docs/DESIGN.md's quality gates say the same in a line.docs/README.md— the first section is now "Reference", the name of its group on the site.README.md,skills/restest/SKILL.mdand its copy indocs/for-coding-agents.md— the site's address, and, for agents,llms.txt.AGENTS.md— a row of "Where things are" for the site.docs/schemas.md— a line that began with> plan.yaml, which Markdown, GitHub's included, showed as a quote.Evidence
DocumentationSiteTest, with three tests (the repository, a well-formed documentation, and 24 broken ones);DocumentedLinksTestrefuses a link to a page's title../mvnw verify: all green, 157 architecture and documentation tests. — the checks of this pull requestnpm run sync -- --from <this checkout> && npx astro build): 76 pages, every internal link valid, the first group named "Reference".actionlintis clean on the workflow. Its comparison tried against the site's realrestest-version(v2.4.0):v2.5.0andv2.10.0are written,v2.4.0is there already,v2.3.0is left, and a missing file is written.Decisions taken
isa-group.github.io/restest-sitefor now (maintainer). When the project has a domain, the README, the skill, ADR-0047,docs/ci.mdand the workflow change with it, and GitHub sends the old address on.llms.txtis named in the skill too (maintainer), so an agent can read a page the skill does not cover; the skill says it describes the latest release, which may not be the version run.restest-versionnever goes back (maintainer). Hence the step before every tag: the site built by hand frommasterafter the pull request that prepares the release, since its weekly build is older than that pull request.restest-versionholds the tag with itsv, the only form the site reads; versions are compared without it, sincesort -Vwould otherwise rankv2.4.0above2.5.0and leave the site behind with a green run.documentation-site.yml, notsite.yml, the name of the site's own workflow, so that "the run of site.yml" is never ambiguous.main. ADR-0047 lists what only the site checks: links in raw HTML, reference-style links, links leaving the repository, headings the site names differently from GitHub, and two files at one address.homebrew.ymlandjbang.yml, which would change both; aversion.jsonon the site in place of the sentence ofllms.txtthe workflow waits for, which ADR-0047 records; reporting a missing index as a problem rather than the failure to read it, which names the file already.Open questions
docs/ci.mddescribes: the environmentrestest-sitein this repository, limited tomasterandv*, created first; an SSH deploy key with write access onisa-group/restest-site; its private half asRESTEST_SITE_KEYin that environment. Then run the workflow by hand frommasterwithv2.4.0:pushshould find the tag there already, andcheck-publishedshould be green.llms.txt's opening sentence saying this workflow waits for it, its README in the present tense, and Mermaid diagrams before 2.5.0, the first release with one.masterAGENTS.mdhold🤖 Generated with Claude Code