Skip to content

Take the empty IDL module out of the build until it holds code - #402

Merged
ssegura merged 1 commit into
masterfrom
chore/idl-module-out-of-the-reactor
Oct 14, 2026
Merged

ssegura merged 1 commit into
masterfrom
chore/idl-module-out-of-the-reactor

Conversation

@ssegura

@ssegura ssegura commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Related: None

What you can do now that you could not before

A release no longer carries an empty restest-idl jar, and the repository no longer lists a module
for the IDL language, inter-parameter dependencies, that nothing reads yet. The known limitations now
say plainly that dependencies between parameters are not read, which a user of RESTest 1.x will look
for.

Try it yourself

git fetch && git switch chore/idl-module-out-of-the-reactor
./mvnw -q package -DskipTests
dist/assemble.sh target/dist > /dev/null && ls target/dist/restest-*/lib | grep '^restest-'

Real output:

restest-cli-2.1.1-SNAPSHOT.jar
restest-core-2.1.1-SNAPSHOT.jar
restest-exec-2.1.1-SNAPSHOT.jar
restest-gen-2.1.1-SNAPSHOT.jar
restest-oracles-2.1.1-SNAPSHOT.jar
restest-report-2.1.1-SNAPSHOT.jar
restest-spec-2.1.1-SNAPSHOT.jar
restest-store-2.1.1-SNAPSHOT.jar

On master the list also has restest-idl-2.1.1-SNAPSHOT.jar, whose only class is
module-info.class.

How it works

RESTest is built from modules that may only depend inwards, towards restest-core. One of them,
restest-idl, was created at the start to hold the IDL language and a constraint solver, and has held
nothing else since. It was still compiled, packaged, copied into every release and listed among what
the tool is made of.

It leaves the build until the first code that reads IDL arrives. The rule that checks the dependencies
between modules keeps a place for it, so it comes back exactly where ADR-0004 put it, checked from its
first class.

What changed in the code

  • Removed: restest-idl/ and the dependencies of restest-gen, restest-cli and restest-arch-tests
    on it; the two requires io.restest.idl in module-info.java.
  • ArchitectureRules: unchanged, with a comment on why the Idl layer stays.
  • AGENTS.md, docs/DESIGN.md, docs/ci.md, the root and arch-tests pom.xml comments: eight
    production modules.
  • ADR-0004 and ADR-0010 amended, and the index; docs/known-limitations.md says dependencies between
    parameters are not read.

Evidence

  • Tests: none added; ./mvnw verify green locally. CI: this pull request's checks.
  • Architecture tests: unchanged, none weakened; the layered rule keeps its Idl layer.
  • Mutation score: not applicable.
  • Per-request overhead: not applicable.
  • Smoke run, two containerised APIs: the smoke job of this pull request.
  • Idle time: not applicable.
  • Artefact: the list above.

Decisions taken

  • The module leaves; the rule's layer stays. Removing the layer would have been a change to an
    architecture test for no gain, and keeping it means nothing has to be decided again when IDL arrives.
  • AGENTS.md changes because it lists the modules; ADR-0030 says such a change is made in a pull
    request, and this is one.
  • Order of merging. Run the command-line tests three at a time, and check the oracles' mutation score on every change #391, which runs the command-line tests three at a time, edits the same
    paragraph of docs/ci.md, and Move master to 2.2.0-SNAPSHOT #397, which moves to 2.2.0-SNAPSHOT, changes restest-idl/pom.xml;
    whichever is merged second keeps the eight modules and deletes the file.

Open questions

None.


  • 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

`restest-idl` held a `module-info.java` and nothing else. It was compiled, packaged as an empty
jar, copied into every release archive and image, depended on by the generation and command-line
modules, and listed in AGENTS.md as the home of "IDL language, constraints, solver interface",
while nothing reads IDL. A user of RESTest 1.x, for whom dependencies between parameters were the
point, could find no word saying they are not read.

The module and the two dependencies on it go; eight production modules remain. The layered
architecture rule keeps its `Idl` layer, which it already allowed to be empty, so a module holding
IDL comes back into the place ADR-0004 decided for it, checked from its first class. ADR-0004 and
ADR-0010 are amended, AGENTS.md, DESIGN.md and the CI page count eight modules, and the known
limitations say that dependencies between parameters are not read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssegura
ssegura merged commit 11abd61 into master Oct 14, 2026
18 checks passed
@ssegura
ssegura deleted the chore/idl-module-out-of-the-reactor branch October 14, 2026 17:14
ssegura added a commit that referenced this pull request Oct 14, 2026
… rather than moving to 2.2.0-SNAPSHOT

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ssegura added a commit that referenced this pull request Oct 14, 2026
…tation score on every change (#391)

**Related:** None. Builds on #390.

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

Nothing a user sees changes. A contributor gets an answer from CI sooner
- the command-line tests run
three classes at a time - and a pull request that weakens the oracles'
tests now fails CI, because
the mutation score of `restest-oracles` is checked on every change
rather than only when somebody
remembers to run it.

## Try it yourself

The mutation score, as one row of CI now runs it:

```bash
git fetch && git switch ci/faster-rows
./mvnw --batch-mode --no-transfer-progress -Pmutation verify -pl restest-oracles -am -Djacoco.skip=true
```

Real output, the lines that matter, in 15 seconds on the maintainer's
Mac:

```
>> Generated 176 mutations Killed 170 (97%)
[INFO] BUILD SUCCESS
```

The command-line tests, now three classes at a time:

```bash
./mvnw verify -pl restest-cli -am
```

| `restest-cli`'s tests, on the maintainer's Mac | one process | three |
|---|---|---|
| wall time | 3 min 1 s | 1 min 30 s |

## How it works

Most of the build's time is the command-line tests, which run the whole
tool against a stand-in API
and spend their time waiting for it to answer. Each test class has a
stand-in of its own on a port of
its own and writes under a directory of its own, and RESTest keeps no
global state, so three classes
can run side by side in three processes without touching each other.

Mutation testing changes the oracles' own code on purpose - a comparison
flipped, a call removed - and
checks that the tests notice. `docs/ci.md` said it "costs minutes" and
left it to be run by hand; it
takes about ten seconds, so the Linux / Java 25 row now runs it after
the build, through a `mutation`
profile that leaves the ordinary `./mvnw verify` as it was.

## What changed in the code

- `restest-cli/pom.xml`: `forkCount` 3, `reuseForks` true, with the
reason.
- `restest-oracles/pom.xml`: a `mutation` profile binding PIT's
`mutationCoverage` to `verify`; the
  comment says it is run on one row of CI.
- `.github/workflows/ci.yml`: a step after the build on the
`ubuntu-latest` / Java 25 row; the triggers
no longer name `v2`, a branch no commit has reached since 3 October and
76 commits behind `master`.
- `docs/ci.md`: the triggers, the mutation score as a gate, the five
production rules its table of
gates did not name, and four sentences written when the modules were
still empty.
- `CONTRIBUTING.md`: the sentence that said the mutation threshold is
run on demand.

## Evidence

- [x] Tests: none added; `./mvnw verify` green locally. CI: this pull
request's checks, including the
      new mutation step on the Linux / Java 25 row.
- [x] Architecture tests: unchanged, none weakened.
- [x] Mutation score: 97%, 170 of 176 (threshold 85%), unchanged; now
checked on every change.
- [x] Per-request overhead: not touched.
- [x] Smoke run, two containerised APIs: the smoke job of this pull
request.
- [x] Idle time: not touched.
- [x] Artefact: the two outputs above.

## Decisions taken

- **Three processes, not more.** GitHub's runners have four cores; on a
laptop three already halves the
time. The gain on CI will be smaller than on the Mac, and is not
measured yet.
- **This needs #390, and brings its branch in.** The first CI run of
this pull request, on `master` as it
is, failed on Linux and Windows: with three processes on four cores, the
tests that gave a run one
to three seconds of the clock spent them starting up and sent nothing
(`CheckSwitchesCommandTest`,
`AuthCommandTest`, `ABrokenRunAnswersFourTest`,
`AKeyIsWrittenNowhereTest`). #390 gives those runs a
number of requests instead, so this branch brought #390's branch in;
#390 is merged now, and
`master` has been merged into this branch since, so its diff shows only
its own changes.
- **The mutation step on one row only.** The score does not depend on
the operating system or the
  Java version.
- **A profile rather than an execution in every build,** so `./mvnw
verify` on a laptop costs what it
  did.
- **Merged with #402.** #402, which took the empty IDL module out of the
build, edited the same
paragraph of `docs/ci.md`; `master` has been merged into this branch
since, keeping both: eight
  modules, and a build of a couple of minutes.

## 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 Fable 5.1 <noreply@anthropic.com>
ssegura added a commit that referenced this pull request Oct 14, 2026
**Related:** None

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

A build of `master` says it is 2.2.0-SNAPSHOT, the version being
prepared, in `restest version` and in
every `report.json` it writes.

## Try it yourself

```bash
git fetch && git switch chore/2.2.0-snapshot
./mvnw -q install -DskipTests
dist/version.sh
./restest version
```

Real output:

```
2.2.0-SNAPSHOT
RESTest 2.2.0-SNAPSHOT
Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
```

On `master` both say 2.1.1-SNAPSHOT.

## How it works

Since 2.1.0 the plan RESTest carries has new shares, a dictionary has
one shape and the plan's format
is at version 2; the last two refuse files 2.1 read. That is a minor
version, as the release notes of
2.2.0 will say, and the JSON Schemas' `$id`s, two decision records and
the release workflow's example
already name 2.2.0. Every `pom.xml` still said 2.1.1-SNAPSHOT. Nothing
would have caught it until the
pull request that prepares the release: the schemas' test only asks that
their version be no older
than the build's.

## What changed in the code

The `<version>` of the ten `pom.xml` files. Nothing else.

## Evidence

- [x] Tests: none added; `./mvnw verify` green locally. CI: this pull
request's checks.
- [x] Architecture tests: unchanged, none weakened;
`PublishedSchemasTest` holds the schemas' `$id`s
      against the new version.
- [x] Mutation score: not applicable.
- [x] Per-request overhead: not applicable.
- [x] Smoke run, two containerised APIs: the smoke job of this pull
request.
- [x] Idle time: not applicable.
- [x] Artefact: the output above.

## Decisions taken

- **Merged with #402.** #402 took the empty IDL module, and its
`pom.xml`, out of the build;
`master` has been merged into this branch since, so the ten that remain
move to 2.2.0-SNAPSHOT.

## 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 Fable 5.1 <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