enhancement
major
major
minor
#29790
Upgrade guide 7.11 to 8.0: add the Maven >= 3.8.9 requirement, state that 7.10.x applications can follow it, and point to it from the release notes
Follow-up to #29612 (upgrade-7.11-to-8.0.md, now part of the developer documentation in com.top_logic/src/main/java/META-INF/tl-docs/). Found while upgrading a small application from 7.10.2 to 8.0.0-alpha10 with the guide; the guide worked well otherwise.
Missing steps
- Maven >= 3.8.9. #29702 raised the requireMavenVersion enforcer rule in tl-parent-all to 3.8.9 on 2026-09-30, after the guide was written (2026-09-17); #29702 has no RequiresMigration keyword. Phase 1.1 says "No new JVM flags are needed" but does not mention the Maven version, so a build with e.g. Maven 3.8.7 (current Debian/Ubuntu package) stops at the enforcer: {{{
Rule 0: org.apache.maven.enforcer.rules.version.RequireMavenVersion failed with message: Detected Maven Version: 3.8.7 is not in the allowed range [3.8.9,). }}} Add to phase 1.1: Maven 3.8.9 or newer is required; a Maven wrapper (mvn -N wrapper:wrapper -Dmaven=3.9.x) is the project-local way if the system Maven is older.
- Java binding generation. An application that binds tl:generate-java to generate-sources cannot build after the parent bump, see #29789. Also worth a sentence: an application whose POM has no own <version> inherits the TopLogic version, so its own artifact changes coordinates with every upgrade.
Clarification
The guide states 7.11.0 as the base. 7.11.0 has no ticket with the RequiresMigration keyword, so a 7.10.x application can follow the guide unchanged (verified with 7.10.2). Say so in the introduction, otherwise 7.10.x users look for a separate 7.10 to 7.11 path.
Discoverability
The guide ships only inside the 8.0 jars (tl-docs). An application still on 7.x cannot see it via its developer documentation (list_docs of the tl-mcp server lists only the docs of the modules on its class path), and the release notes on dev.top-logic.com list only the migration tickets of the respective (alpha) release, with no cumulative view. Someone upgrading from 7.x therefore only finds it by browsing the engine repository on GitHub.
Lösung
In upgrade-7.11-to-8.0.md:
- Introduction: a 7.10.x application follows the guide unchanged, there is no separate 7.10 to 7.11 path.
- Phase 1.1: Maven 3.8.9 or newer is required (#29702), with the enforcer message and the Maven wrapper as the project-local remedy.
- Phase 1.1, POM hygiene: an application POM without an own <version> inherits the TopLogic version; declare an own version.
- Appendix A: #29702 is listed as a change without migration section.
The binding generation (#29789) is not described in the guide: #29789 is planned for 8.0.0, the target version of the guide.
Discoverability: this ticket carries RequiresMigration, so the migration section below - the pointer to the guide - appears in the release notes of the release it lands in and of 8.0.0. Nothing is shipped with 7.x.
Migration
An application is upgraded from TopLogic 7.10 or 7.11 to 8.0 following the upgrade guide upgrade-7.11-to-8.0 of the developer documentation (shipped in tl-core, readable with the read_doc tool of the tl-mcp server and in the documentation window of a React application): https://github.com/top-logic/tl-engine/blob/TL_8.0.0/com.top_logic/src/main/java/META-INF/tl-docs/upgrade-7.11-to-8.0.md
The guide covers all changes of 8.0 that require a migration step, including those whose tickets have no migration section, in the order in which they have to be done.