Skip to content

Read and search the documentation at one address, moved on to each release once it is published - #439

Merged
ssegura merged 1 commit into
masterfrom
feat/m12-4-documentation-site
Nov 6, 2026
Merged

ssegura merged 1 commit into
masterfrom
feat/m12-4-documentation-site

Conversation

@ssegura

@ssegura ssegura commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator

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:

git clone --branch feat/m12-4-documentation-site https://github.com/isa-group/RESTest.git restest-docs-site
cd restest-docs-site
./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.Documentation*,io.restest.arch.DocumentedLinksTest' \
  -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Tests run:.*in io|BUILD'
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.179 s -- in io.restest.arch.DocumentationSiteTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.044 s -- in io.restest.arch.DocumentedLinksTest
[INFO] BUILD SUCCESS

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:

printf '# Faults, again\n\nThe same page twice.\n' > docs/faults-again.md
printf '\nSee [the command line](command-line.md#the-command-line).\n' >> docs/faults.md
./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.Documentation*,io.restest.arch.DocumentedLinksTest' \
  -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Expecting empty|BUILD' | sort -u
Expecting empty but was: ["docs/README.md lists no entry for docs/faults-again.md, so the website's menu would not reach it; every page needs one, in it or in docs/manual/README.md"]
Expecting empty but was: ["docs/faults.md links to command-line.md#the-command-line, and docs/command-line.md has no heading by that name"]
[INFO] BUILD FAILURE

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":

git clone https://github.com/isa-group/restest-site ../restest-site && cd ../restest-site
npm ci && npm run sync -- --from ../restest-docs-site && npx astro build | grep -E 'valid|built in'
grep -o '"label": *"Reference"' src/generated/sidebar.json
Copied 76 pages and 5 images of RESTest at master, from …/restest-docs-site
· All internal links are valid. ·
[build] 77 page(s) built in 1.35s
"label": "Reference"

The workflow cannot be tried before it is on master and 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 file restest-version and reads the Markdown under docs/, README.md, AGENTS.md and CONTRIBUTING.md as they are; its menu comes from the two indexes, the manual's numbered list of chapters and one group per ## section of docs/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.yml writes its tag into the site's restest-version with a deploy key, as homebrew.yml and jbang.yml write 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's llms.txt names 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: DocumentationSiteTest holds every pull request to the rules the site builds by, and before a tag the site is built by hand from master (a new step in the release steps of docs/ci.md).

What changed in the code

  • .github/workflows/documentation-site.yml — three jobs: version checks the tag and that it is a published release; push, in the environment restest-site, writes the tag into the site with the key RESTEST_SITE_KEY, checking out nothing of RESTest while the key is loaded; check-published waits 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 of docs/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.md lists 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.md and its copy in docs/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

  • Tests: one class added, DocumentationSiteTest, with three tests (the repository, a well-formed documentation, and 24 broken ones); DocumentedLinksTest refuses a link to a page's title. ./mvnw verify: all green, 157 architecture and documentation tests. — the checks of this pull request
  • Architecture tests: 157, none weakened; the rule on links is stricter.
  • Mutation score: not applicable; no oracle or constraint touched.
  • Per-request overhead: not applicable.
  • Smoke run: not applicable; nothing a run does changes.
  • Idle time: not applicable.
  • Artefact: the site built from this branch with its own script (npm run sync -- --from <this checkout> && npx astro build): 76 pages, every internal link valid, the first group named "Reference". actionlint is clean on the workflow. Its comparison tried against the site's real restest-version (v2.4.0): v2.5.0 and v2.10.0 are written, v2.4.0 is there already, v2.3.0 is left, and a missing file is written.

Decisions taken

  • The site documents the latest release, and is moved on by a deploy key when one is published (maintainer), as Homebrew's tap and the jbang catalog are.
  • The site's address is isa-group.github.io/restest-site for now (maintainer). When the project has a domain, the README, the skill, ADR-0047, docs/ci.md and the workflow change with it, and GitHub sends the old address on.
  • llms.txt is 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.
  • A release whose pages the site cannot build: the site is changed until it builds that tag, and restest-version never goes back (maintainer). Hence the step before every tag: the site built by hand from master after the pull request that prepares the release, since its weekly build is older than that pull request.
  • restest-version holds the tag with its v, the only form the site reads; versions are compared without it, since sort -V would otherwise rank v2.4.0 above 2.5.0 and leave the site behind with a green run.
  • The workflow is documentation-site.yml, not site.yml, the name of the site's own workflow, so that "the run of site.yml" is never ambiguous.
  • A Java test that restates the site's rules, rather than running the site's own build on RESTest's pull requests: that would be one set of rules, but Node in RESTest's CI and every pull request here depending on the site's 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.
  • ADR-0031 is amended: its manual "has one rendering", which the site makes untrue.
  • Not taken from reviewers: a reusable workflow shared with homebrew.yml and jbang.yml, which would change both; a version.json on the site in place of the sentence of llms.txt the 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

  • Before 2.5.0 is published, set up once what docs/ci.md describes: the environment restest-site in this repository, limited to master and v*, created first; an SSH deploy key with write access on isa-group/restest-site; its private half as RESTEST_SITE_KEY in that environment. Then run the workflow by hand from master with v2.4.0: push should find the tag there already, and check-published should be green.
  • In the site, a small pull request follows: a comment beside 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.

  • Targets master
  • English throughout, including comments and test names
  • The hard rules in AGENTS.md hold

🤖 Generated with Claude Code

…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
ssegura merged commit 1c0d999 into master Nov 6, 2026
21 of 22 checks passed
@ssegura
ssegura deleted the feat/m12-4-documentation-site branch November 6, 2026 07:35
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>
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant