Skip to content

Release 2.5.0: jbang, a skill for coding agents, and the documentation at one address - #442

Merged
ssegura merged 2 commits into
masterfrom
release/2.5.0
Nov 10, 2026
Merged

ssegura merged 2 commits into
masterfrom
release/2.5.0

Conversation

@ssegura

@ssegura ssegura commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

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

Try it yourself

From a clean clone, with only Java and git:

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:

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:

./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):

  • 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 Tell a build of master from the 2.4.0 release: master moves on to 2.5.0-SNAPSHOT #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 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

  • 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 run is green, central and publish skipped, as on every pull request. On the second push, CI'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.
  • Architecture tests: unchanged, none weakened.
  • Mutation score: no oracle or constraint touched.
  • Per-request overhead: unchanged; nothing under src/ changed.
  • Smoke run: unchanged, for the same reason; CI runs it on this pull request.
  • Idle time: unchanged.
  • 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

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.


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

🤖 Generated with Claude Code

ssegura and others added 2 commits November 10, 2026 18:02
…n at one address

Every pom.xml from 2.5.0-SNAPSHOT to 2.5.0; the README and chapters 2 and 9 of the manual install and
run 2.5.0, with the output of the archive and the image built from this commit. The schemas' $id names
v2.5.0 already, and the base images are the newest patch already.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s run of release.yml printed them

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssegura
ssegura merged commit 8db5ed1 into master Nov 10, 2026
30 of 33 checks passed
@ssegura
ssegura deleted the release/2.5.0 branch November 10, 2026 17:39
ssegura added a commit that referenced this pull request Nov 10, 2026
….0-SNAPSHOT (#444)

**Related:** None. This is the step after the 2.5.0 release, the last of
`docs/ci.md`'s release steps.

## What you can do now that you could not before

Tell a build of `master` from the release. `v2.5.0` is tagged and
[published](https://github.com/isa-group/RESTest/releases/tag/v2.5.0),
and its modules are on Maven Central. From here on, a build of `master`
says `RESTest 2.6.0-SNAPSHOT` in `restest version` and in every
`report.json`, so a report produced by code that came after 2.5.0 is
never taken for one produced by 2.5.0 itself.

## Try it yourself

```bash
git clone --quiet -b chore/2.6.0-snapshot https://github.com/isa-group/RESTest.git restest-snapshot && cd restest-snapshot
./mvnw -q install -DskipTests
./restest version
grep -h '"\$id"' schemas/*.json
```

Real output, from a fresh clone of this branch on 10 November (the Java
line is your own):

```
RESTest 2.6.0-SNAPSHOT
Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
  "$id": "https://raw.githubusercontent.com/isa-group/RESTest/v2.6.0/schemas/dictionary.schema.json",
  "$id": "https://raw.githubusercontent.com/isa-group/RESTest/v2.6.0/schemas/campaign.schema.json",
```

## How it works

The version lives in the build files, and the tool reads it from there.
`-SNAPSHOT` is how Maven writes "on the way to this version, not yet
published". The tag `v2.5.0` keeps the commit that says 2.5.0; `master`
moves on to the next version and drops the `-SNAPSHOT` again when that
one is released.

The JSON Schemas of a dictionary and a plan name the release they
describe in their `$id`, the address each is published at. On `master`
that is the release being prepared, `v2.6.0`, which
`PublishedSchemasTest` requires to be no older than the snapshot.

## What changed in the code

No Java code and no page changed.

- The ten `pom.xml`, from `2.5.0` to `2.6.0-SNAPSHOT`, with `./mvnw
versions:set`.
- `schemas/campaign.schema.json` and `schemas/dictionary.schema.json`:
`$id` from `…/v2.5.0/…` to `…/v2.6.0/…`.

## Evidence

- [x] **Tests:** `./mvnw clean install` green on this branch: 4,981
tests, 0 failures, BUILD SUCCESS in 2 min 37 s. Among them are the 76
tests of `PublishedSchemasTest`. On
[CI](https://github.com/isa-group/RESTest/actions/runs/42876875507)'s
first attempt two rows failed, each in a test this pull request does not
touch, and both were re-run:
- *Java 26 on ubuntu-latest*, in
`EngineFaultsTest.a_redirection_nowhere_is_a_wait_for_a_connection`,
which follows a redirection to a port that accepts the connection and
never answers, with a read timeout of 300 ms, and expects a wait for a
connection: it got a wait for a reply, the timeout having run out in a
part of the exchange the engine counts as the reply.
- *Java 25 on macos-latest*, in
`FuzzingFindsWhatNominalMissesTest.the_awkward_values_are_what_find_it`,
which expects the empty search term among the awkward values of a run of
1,200 requests: with seed `1749106978450864122`, its 120 awkward values
did not include it, though the test's comment says that size reaches it
every time.

Both depend on timing or chance, as
`RunLoopTest.an_operation_told_to_wait_is_skipped` did in #442; they are
put right in a pull request of their own.
- [x] **Architecture tests:** unchanged, none weakened.
- [x] **Mutation score:** not touched.
- [x] **Per-request overhead:** not touched.
- [x] **Smoke run:** not touched.
- [x] **Idle time:** not touched.
- [x] **Artefact:** the installation of 2.5.0 was tried from outside on
10 November, as the README gives it, with no one signed in to GitHub, to
the registry or to Maven Central:
- **Homebrew:** publishing the release started
[`homebrew.yml`](https://github.com/isa-group/RESTest/actions/runs/42871411688),
and all six of its jobs are green. It wrote `restest 2.5.0` into
`isa-group/homebrew-tap`, with the checksum `checksums_sha256.txt` gives
`restest-2.5.0.tgz`, and installed it from there on macOS and on Linux,
628 MB and 824 MB as chapter 2 of the manual says. `brew install
isa-group/tap/restest` on a Mac with neither the tap nor RESTest
installed it too, with an `openjdk@21` of its own, and `restest version`
printed `RESTest 2.5.0` on `Java 21.0.13.0.3 (Homebrew)`.
- **jbang:** publishing the release started
[`jbang.yml`](https://github.com/isa-group/RESTest/actions/runs/42871411661),
and all six of its jobs are green. The catalog names
`es.us.isa.restest:restest-cli:2.5.0`, and `jbang --fresh
restest@https://isa-group.github.io/jbang-catalog/jbang-catalog.json
version`, with a jbang folder of its own, printed `RESTest 2.5.0`. Its
`check` jobs count 38 to 39 MB of libraries on Linux and macOS and 37 on
Windows, what they counted on 1 November when chapter 2 was written, so
its 37 MB stay.
- **The image:** `ghcr.io/isa-group/restest:2.5.0`, pulled with an empty
Docker configuration, printed `RESTest 2.5.0` on Java 21.0.13. Chapter
2's `restest` script, written into a `HOME` of its own, ran a run
against nothing that ended with `3` and left `report.json` and
`report.html` in the folder, owned by the user. The registry gives
`:latest` the same digest, `sha256:3e72646c…`.
- **The archive:** `restest-2.5.0.tgz` and `checksums_sha256.txt`,
downloaded with `curl`. `shasum -a 256 -c` answered `OK`, `restest
version` printed `RESTest 2.5.0`, and `skills/restest/SKILL.md` is in
it.
- **The source:** `git clone --branch v2.5.0`, with no credential
helper, followed by `./mvnw -q install -DskipTests` printed `RESTest
2.5.0`.
- **Maven Central:**
`https://repo1.maven.org/maven2/es/us/isa/restest/restest-cli/2.5.0/`
answers, and all 128 files of the eight modules are there. A project
that depends on `es.us.isa.restest:restest-cli:2.5.0`, resolved from
Central into an empty local repository, got 71 jars, the same names and
the same bytes as the release archive's `lib/`, and `restest version`
run from them printed `RESTest 2.5.0`.
- **The documentation site:** publishing the release started
[`documentation-site.yml`](https://github.com/isa-group/RESTest/actions/runs/42871411673),
and all three of its jobs are green.
https://isa-group.github.io/restest-site/llms.txt now names 2.5.0, and
the page for coding agents the README sends an agent to answers.

## Decisions taken

- **2.6.0, not 2.5.1:** the next release is meant to add features, which
semantic versioning makes a minor version.
- **No release step changes.** All eight of `docs/ci.md`'s steps worked
for 2.5.0 as they are written, including the first publication of the
jbang catalog for a release and the documentation site's move to it, so
neither that page nor an ADR is touched.

## Open questions

None.

---

- [x] Targets `master`
- [x] English throughout, including comments and test names
- [x] The hard rules in `AGENTS.md` hold
- [x] Nothing from "Out of scope" in `docs/DESIGN.md` without explicit
approval

🤖 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