[ssegura]

Related: None. This is the release of 2.2.0, prepared after an evaluation of its candidate against 2.1.0, which the maintainer asked for on 22 October.

What you can do now that you could not before

• Get 2.2.0 three ways. Once this is merged and tagged, RESTest runs with nothing but Docker (docker run ghcr.io/isa-group/restest:2.2.0), with nothing but Java from the release's archive, or built from the source as before; the README and the manual's chapter 2 say how, each ending with restest as a command on the PATH, which scripts and coding agents find as a terminal does.
• Know what the archive and the image hand on. Both carry THIRD-PARTY.txt, every library in them with the licence it is used under and the texts those licences ask to travel with every copy, and no release can be assembled with a library the file does not list.

Try it yourself

From a clean clone, with only Java and git:

git clone -b release/2.2.0 https://github.com/isa-group/RESTest.git && cd RESTest
./mvnw -q install -DskipTests
./restest version
dist/assemble.sh ../release --archives > /dev/null && ls ../release
tar -xzf ../release/restest-2.2.0.tgz -C .. && ls ../restest-2.2.0
../restest-2.2.0/bin/restest version
grep -c '^  lib/' ../restest-2.2.0/THIRD-PARTY.txt

Real output, in a fresh clone of this branch on 23 October (the Java line is your own):

RESTest 2.2.0
Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
restest-2.2.0
restest-2.2.0.tgz
restest-2.2.0.zip
LICENSE
NOTICE
README.md
THIRD-PARTY.txt
bin
lib
schemas
RESTest 2.2.0
Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
63

A library the list leaves out stops the release. In the same clone:

sed -i.bak '/lib\/picocli-/d' dist/THIRD-PARTY.txt
dist/assemble.sh ../release; echo "exit $?"
mv dist/THIRD-PARTY.txt.bak dist/THIRD-PARTY.txt

dist/assemble.sh: dist/THIRD-PARTY.txt does not list exactly the libraries RESTest runs with:
    lib/picocli-4.7.7.jar is carried but not listed
exit 1

With Docker as well, the image is built from the same clone as the release builds it:

docker build --tag restest:2.2.0 . && docker run --rm restest:2.2.0 version

RESTest 2.2.0
Java 21.0.12.1 (Eclipse Adoptium), Linux 7.0.14-linuxkit aarch64

The pages to read are the README's Installation and use and the manual's chapter 2.

How it works

The version. -SNAPSHOT is how Maven writes "on the way to this version". This pull request removes it from every pom.xml. After the merge, the tag v2.2.0 on the merge commit starts the release workflow, which builds the image and the archives, checks them on three operating systems and two processors, pushes the image, and leaves a draft release for a maintainer to write the notes in and publish (docs/ci.md).

The libraries' licences. Until 2.2.0 nobody received RESTest's libraries from RESTest: Maven fetched each from its own project. The archive and the image now hand on 63 of them, and some licences — MIT, the BSD-style Eclipse Distribution License, the Mozilla Public License — ask that their text and copyright lines go with every copy. dist/THIRD-PARTY.txt lists every library under its licence and carries those texts; the Apache License, which most of them and RESTest share, is LICENSE beside it. The list is written by hand, and the script that assembles a release compares it with the libraries it is about to pack: a dependency added, dropped or moved to another version stops the release, and the image job of every pull request, until someone writes its line and reads its licence.

The pages. The installation sections had one way in, building from the source, and the manual's examples ran ./restest from a checkout. They now give the image, the archive and the source, and write restest, which each way puts on the PATH: the archive's bin/, the checkout, or, for Docker, a two-line script that runs the image. That script also lends the current folder to the container, hands on RESTEST_AUTH, and lets it reach the machine it runs on as host.docker.internal, since inside a container localhost is the container itself; on Linux, an API that listens only on 127.0.0.1 needs --network host instead. Chapters 2, 7 and 10 say what that changes. The README's first run and chapter 3 are new runs of 2.2.0, which print errors and warnings.

What changed in the code

• dist/THIRD-PARTY.txt (new): 49 libraries under the Apache License 2.0, 8 under it or the LGPL (used under Apache), 3 under MIT (jopt-simple, whose jar carries no licence, and SLF4J), 2 under the Eclipse Distribution License (the Jakarta Activation and XML Binding APIs), and Rhino under the MPL 2.0, with where its source is. The MIT, EDL and MPL texts, and Rhino's and SQLite JDBC's own notices, are copied from the jars; jopt-simple's from its project at the tag jopt-simple-5.0.4. okhttp, guava and httpclient carry the Public Suffix List, under the MPL 2.0, and the list says so.
• dist/assemble.sh: compares the lib/…jar lines of the list with the jars in restest-cli/target/lib other than RESTest's own, names each that is carried but not listed or listed but not carried, and ends with 1; then copies the list beside LICENSE and NOTICE.
• .github/scripts/check-restest.sh: the image must have /opt/restest/THIRD-PARTY.txt, and a release's folder THIRD-PARTY.txt; its header says so.
• ADR-0032: an amendment of 23 October 2026 on the list and its check. docs/ci.md's row for how RESTest starts and its section on dependency updates, the ADR index, and the README's License section follow.
• Version: every pom.xml from 2.2.0-SNAPSHOT to 2.2.0, with ./mvnw versions:set. The JSON Schemas' $id already names v2.2.0.
• Dockerfile: the digests of eclipse-temurin:25-jdk and 21-jre as they are today. Same Java, 25.0.4.1 and 21.0.12.1; a newer Ubuntu underneath (step 1 of a release while Dependabot is off).
• README.md: "What you need" and "Install" with the three ways, the source one cloning v2.2.0; "Your first run" and its prose from a run of 2.2.0 against the online pet store, showing an error, a warning and an F206 on the same request; "Reading what it says" describes errors and warnings; restest for the command throughout.
• The manual:
  • chapter 1: what you need, and that examples write restest;
  • chapter 2: rewritten around the three ways, with real output of docker run … version, of the archive's bin/restest version, and of its refusal of Java 17; the checksums; Linux's --network host; updating each way;
  • chapter 3: the first run and its prose from a run of 2.2.0 against pet-clinic 4.0.2;
  • chapter 7: a setting's variable reaches the image only through -e;
  • chapter 9: the workflow fetches the archive (curl … | tar -xz) in place of cloning and building v2.1.0;
  • chapter 10: the archive's 127, Docker's localhost, and the folder lent as /work;
  • chapters 4 to 9: restest for ./restest.
• docs/report.md: the README run's first lines and last line as they are now, and a sentence Say everywhere what 2.2.0 does, before it is released #410 left cut in two.
• docs/manual/README.md: chapter 2's line in the contents.
• docs/known-limitations.md: two entries from the release evaluation. Many F206 are an API reading leniently what its document forbids: 22 of 28 read by hand were. And a path parameter the path has no place for gives a false F206.

Evidence

• Tests: ./mvnw verify green at the tip of this branch, with version 2.2.0: 4,648 tests, 0 failures, BUILD SUCCESS in 1 min 35 s. No test added: the new check is in dist/assemble.sh and check-restest.sh, which the image job of CI runs on every pull request; the first was made to fail here, as "Try it yourself" shows — CI: added below once it has run.
• Architecture tests: unchanged, none weakened; the documentation rules pass with the new pages, DocumentedLinksTest among them.
• Mutation score: no oracle or constraint touched.
• Per-request overhead: unchanged; nothing under src/main changed.
• Smoke run: unchanged, for the same reason. What 2.2.0 does was measured on its candidate, c9658b3d, whose code this is: 52 APIs of the Web Fuzzing Dataset, two seeds, three minutes each, against 2.1.0, and sixteen open-source APIs whose code was measured for branch coverage. No run ended with 2, 3 or 4; no measure of coverage or of server errors found got worse with significance; branch coverage 32.7% → 32.8%, better on 8 APIs and worse on 1 (sign test, p 0.04); and 98 faults were read by hand, which gave the two known limitations.
• Idle time: unchanged.
• Artefact:
  • the image and an archive unpacked into a folder with a space in its name pass check-restest.sh 2.2.0, the new checks included;
  • the restest script of the README and chapter 2, on the PATH, ran against pet-clinic on the same Mac through host.docker.internal, from chapter 9's script run with bash as well as from a terminal; it passed RESTEST_AUTH through, wrote restest-out/report.json into the folder lent, and ended with 130 on an interrupt, its run cut short and reported;
  • in Docker's own Linux machine, an API listening only on 127.0.0.1 was reached with --network host and localhost, and not through host.docker.internal, which ended with 3: what chapter 2 and 10 now say;
  • the checkout and the archive's bin/ put on the PATH answer restest version from another folder;
  • chapter 9's two steps, run here against pet-clinic from the archive (the download replaced by the local file), end the step with 0;
  • every output quoted in the pages is copied from those runs.

Decisions taken

• The list of libraries is written by hand and checked, not generated. license-maven-plugin gave the licence each project declares, which is where the list started; but a tool cannot say what a licence asks a copy to carry, and a new version of a library can change its licence. A check that stops on any difference makes a person look each time a dependency moves. The cost falls on dependency updates: each changes one line of the list.
• The libraries' own NOTICE files stay inside their jars, which the archive carries unchanged, rather than gathered into RESTest's NOTICE. The list says where they are.
• Libraries offered under Apache or the LGPL are used under Apache, so no LGPL text is needed.
• restest on the PATH rather than ./restest, in the README and the manual. With three ways in, ./restest is right for only one. A first draft defined restest with an alias, which the review showed a script and a coding agent never see: chapter 9's script would have ended with 127 and blamed the run. A command on the PATH is found by both. docs/ci.md and AGENTS.md, for people working on RESTest from a checkout, keep ./restest.
• For Docker, a two-line script in ~/.local/bin, rather than a wrapper RESTest would ship: it is written with printf from the page, and says in one line what docker run is handed. It carries --add-host on every system — Linux needs it to know host.docker.internal, and Docker Desktop accepts it — and hands on RESTEST_AUTH only, since -e names one variable at a time; chapter 7 says how to hand on a setting.
• The source install clones v2.2.0, as the release notes do, and updating it fetches and checks out the next tag: git pull fails on a tag.
• Chapter 9's workflow fetches the archive rather than running the image. On a runner, a container reaches a service container on localhost only with --network host, which was not tried here; the archive keeps the workflow's steps as they were and runs on any runner with Java.
• docs/report.md's summary and docs/faults.md's examples stay as Tell errors from warnings, and fail a run on its errors #409 and Say everywhere what 2.2.0 does, before it is released #410 left them. They are runs of c9658b3d, whose code this is, and already print errors and warnings.
• The known limitations say no version. When the false F206 is fixed is not the documentation's to promise; the entry goes when the fix comes.
• The release notes are not in this pull request. They were drafted with the maintainer and go into the draft release after the tag, as docs/ci.md says.

Open questions

• Windows with Docker is not described: the restest script is for a Unix shell, and Git Bash rewrites the -v "$PWD:/work" path. Windows users have the archive's restest.cmd, which CI checks. Worth a page, or left to a user who asks?
• After the merge, each step taken by a maintainer:
  • the tag v2.2.0 on the merge commit;
  • the first image creates ghcr.io/isa-group/restest as a private package, which an owner of the organisation makes public;
  • the notes and the publication;
  • the README's installation commands, tried from outside;
  • the pull request that moves master to 2.2.1-SNAPSHOT.

---

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

🤖 Generated with Claude Code