enhancement
major
minor
defect
critical
major
minor
major
#30104
Nightly preview builds of the engine with a fixed Maven version and a changelog instead of a rolling SNAPSHOT
Context
Projects that build on the engine’s current development status (e.g., the TopLogic/tl-factory tax application) depend on 8.0.0-SNAPSHOT. This status changes without notice: `mvn -U ` fetches the latest build from the `master ` branch. It is not immediately clear which tickets have been added and what adjustments they require. A breakage only becomes apparent during the build or in the running application.
Example: With the snapshot from October 31, 2026, CommitSource (#29952) and the ` system-separator` anchor in the shell `app.view.xml` were removed. This was only detected via a failing test or a check in the browser.
The nightly TL7 build already fully builds and tests the `master` branch, setting the tag `BUILD/BUILD-<n>` in the process. However, fixed Maven versions are only available for alpha releases because, until now, a version specified in ` pom.xml` meant a commit to `master`. This should be avoided so that the history of the POMs does not grow every night.
Improvement
After every successful nightly build (and on demand for any build tag), a preview version with a fixed Maven version is published to the Nexus release repository, along with a list of tickets added since the previous preview version and their migration notes. If a dependent project pins a preview version (<tl.version>8.0.0-alpha12.813</tl.version>), Renovate suggests the next one. A version change is thus a deliberate step involving known tickets and adjustments. If something breaks, the cause lies between two known tags.
Solution
Versioning Scheme
<X.Y.Z>-alpha<N>.<n>:
- X.Y.Z is the version from master without -SNAPSHOT.
- `N` is the highest alpha release of this version (tag `TL_X.Y.Z-alpha<N>`), 0if none exists yet.
- n` is the number of the build tag `BUILD/BUILD-<n>` from which the version is built. It is unique (even if there are multiple builds on a single day) and leads directly to the built version.
According to Maven’s `ComparableVersion ` (tested with 3.9.16), this sorts correctly, even after the 8.0.0 release, when `master` is at 8.1.0-SNAPSHOT:
8.0.0-alpha12 < 8.0.0-alpha12.813 < 8.0.0-alpha13 < 8.0.0 < 8.1.0-alpha0.820 < 8.1.0-alpha1 < 8.1.0
The `0` is necessary: `8.1.0-alpha.820` is sorted after ` 8.1.0-alpha1`. An unknown qualifier such as 8.0.0-preview.813 is sorted after 8.0.0. Since preview versions are pre-release versions, Renovate does not suggest them for a project running on a stable version.
Release without a commit to master (tl-ci)
- The tl-ci-release job (repository tl-ci, release/Jenkinsfile, scripts/release.sh) has the parameters PREVIEW and PREVIEW_RETENTION_DAYS (default 56). With PREVIEW, it releases the build tag FROM_TAG (BUILD/BUILD-<n>) as a preview version: ` release:prepare ` from the maven-release-plugin on a local working branch at the build tag with `pushChanges=false` (the same mechanism as for alpha releases, including the tl.version property in tl-bom), release:perform with localCheckout from the local state; afterward, only the tag is pushed. Tests are not run again—they were already run in the nightly build. No branch of the repository changes; ` master ` remains at X.Y.Z-SNAPSHOT.
- Tag: PREVIEW/TL_<version>, e.g., PREVIEW/TL_8.0.0-alpha12.813. It contains exactly the published source code. The custom namespace keeps the preview versions out of searches for release tags (TL_*). If the tag already exists, the job ends successfully without a build.
- The nightly TL7 build starts tl-ci-release after a successful build with `FROM_TAG=BUILD/BUILD-<n> ` and `PREVIEW=true`. Upon request, tl-ci-release can also be started for any build tag.
- If the change list, the Gitea release, or the cleanup fails after deployment, the build becomes unstable (the version has already been released at that point).
Change Log
For each preview version, a Gitea pre-release is published daily at https://git.top-logic.com/TopLogic/tl-engine-7/releases/tag/PREVIEW/TL_<version>. It lists the tickets from the commits since the previous preview version (or, if there was no previous preview version, since the last release tag) with their type and summary from Trac, with dependency updates (DependencyUpdate) listed separately. The == Migration == sections of tickets marked with the keyword RequiresMigration are listed first, converted from Trac Wiki formatting to Markdown. The list is generated by the subcommand `tl-release preview-notes --since <rev> --until <rev> ` of the `tl-release ` tool (repository ` tl-dev-mcp`), which reuses the ticket identification process for releases. The job reads the Trac account from the Jenkins credential tl-ci-trac (username and password), which it binds only for preview releases as TRAC_USERNAME / TRAC_PASSWORD.
Renovate links the change log via ` prBodyNotes ` in the pull request; the developer article `application-project ` (section “Building on the development state: preview versions”) describes how to use a preview version and the Renovate configuration (`ignoreUnstable: false`, so that Renovate switches to the next preview version even if it skips X.Y.Z ).
Adaptation Notes
The existing release convention applies: A ticket that makes an incompatible change to an API or configuration must include a section titled == Migration == in its description detailing what a dependent project must change, and must carry the keyword RequiresMigration.
Cleanup
Preview tags and their Gitea releases are deleted after 8 weeks (PREVIEW_RETENTION_DAYS). In Nexus, a cleanup policy removes the preview versions after the same period.
Prerequisites on the Jenkins nodes
uv/`uvx`, xmllint, python3, and curl. uv is installed via pipx for the jenkins user; the node variable PATH+LOCAL=/var/lib/jenkins/.local/bin makes it accessible to builds.