Follow-up to #218. That issue proposed reordering the README sections by "relevance" (managed, remote, embedded). The underlying want there is real — a newcomer can't tell which of the three modes they should pick — but reordering sections doesn't actually tell them, it just implies a ranking without stating one. Meanwhile the README has content that is plainly wrong and would have been shuffled around untouched.
So: state the guidance explicitly, and fix the stale bits.
1. Say how to choose a mode
The intro bullets currently just define the modes:
https://github.com/arquillian/arquillian-container-tomcat/blob/main/README.adoc#L18-L20
Extend each with a short when to use this clause, so the choice is explicit rather than encoded in section order. This makes the ordering question moot — and the file already sets :toc: with :toclevels: 1, so all three sections are one click from the top regardless of order.
2. Fix the embedded Maven profile example
The example profile does not resolve as written. README.adoc line 108 lists:
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-logging-juli</artifactId>
<version>${version.tomcat}</version>
<scope>provided</scope>
</dependency>tomcat-embed-logging-juli was never published past Tomcat 7 — the newest version on Maven Central is 7.0.109. With a Tomcat 10 version in ${version.tomcat} this dependency cannot be resolved, so anyone copy-pasting the profile gets a build failure.
For comparison, the actual module needs only two Tomcat artifacts:
https://github.com/arquillian/arquillian-container-tomcat/blob/main/tomcat-embedded-10/pom.xml#L16-L26
Also in the same block: org.eclipse.jdt.core.compiler:ecj is pinned to 3.7 (2011) and should be re-checked for whether it's needed at all alongside tomcat-embed-jasper. This is the // TODO review the dependency set below at README.adoc line 81.
3. Correct inconsistent / stale prose
- Line 28 — Tomcat Embedded says "such as JNDI and Servlet 3.0", but the Default Protocol two sections down (line 63) says Servlet 6.0.
- Line 131 — Tomcat Managed is described as "can run and connect to remote (different JVM, but same machine) Tomcat instances", which reads like the Remote mode's description. Managed should be described in terms of Arquillian owning the lifecycle.
- Line 16 — typo: "There three distinct operation modes" → "There are three...".
Suggest closing #218 in favour of this. The premise there ("managed is the most useful, remote and then embedded") doesn't hold up against this project's own issue history: of the 36 issues filed to date, embedded is the mode users most often show up about (8, vs 6 managed and 4 remote), and they're usage-driven rather than pure breakage — #86 ("we've been consuming the embedded module"), #187, #115, #23, #28. Commit traffic since 2023 is flat across the three modules. The current Embedded → Managed → Remote order is also a coherent axis (increasing distance from the test JVM) and matches the intro bullet list, so any reorder would have to move both together.
Follow-up to #218. That issue proposed reordering the README sections by "relevance" (managed, remote, embedded). The underlying want there is real — a newcomer can't tell which of the three modes they should pick — but reordering sections doesn't actually tell them, it just implies a ranking without stating one. Meanwhile the README has content that is plainly wrong and would have been shuffled around untouched.
So: state the guidance explicitly, and fix the stale bits.
1. Say how to choose a mode
The intro bullets currently just define the modes:
https://github.com/arquillian/arquillian-container-tomcat/blob/main/README.adoc#L18-L20
Extend each with a short when to use this clause, so the choice is explicit rather than encoded in section order. This makes the ordering question moot — and the file already sets
:toc:with:toclevels: 1, so all three sections are one click from the top regardless of order.2. Fix the embedded Maven profile example
The example profile does not resolve as written.
README.adocline 108 lists:tomcat-embed-logging-juliwas never published past Tomcat 7 — the newest version on Maven Central is7.0.109. With a Tomcat 10 version in${version.tomcat}this dependency cannot be resolved, so anyone copy-pasting the profile gets a build failure.For comparison, the actual module needs only two Tomcat artifacts:
https://github.com/arquillian/arquillian-container-tomcat/blob/main/tomcat-embedded-10/pom.xml#L16-L26
Also in the same block:
org.eclipse.jdt.core.compiler:ecjis pinned to3.7(2011) and should be re-checked for whether it's needed at all alongsidetomcat-embed-jasper. This is the// TODO review the dependency set belowatREADME.adocline 81.3. Correct inconsistent / stale prose
Note on #218
Suggest closing #218 in favour of this. The premise there ("managed is the most useful, remote and then embedded") doesn't hold up against this project's own issue history: of the 36 issues filed to date, embedded is the mode users most often show up about (8, vs 6 managed and 4 remote), and they're usage-driven rather than pure breakage — #86 ("we've been consuming the embedded module"), #187, #115, #23, #28. Commit traffic since 2023 is flat across the three modules. The current Embedded → Managed → Remote order is also a coherent axis (increasing distance from the test JVM) and matches the intro bullet list, so any reorder would have to move both together.