The build

This document covers how Linked Data Store (LDS) is built: the Maven reactor and its modules, the rules the build enforces, how the tests run, CI, Renovate, and how a release would be made. It is for developers and maintainers who change a POM, a module descriptor, a workflow or the setup of a test.

What the build is for

The build makes every module of LDS from one repository, with one version, on one JDK. It compiles the modules as named modules with compiler warnings as errors, runs the tests against the real engines in containers, checks the Javadoc, and puts together the jars the server image is made of.

The build publishes nothing. No artifact and no image leaves the machine that builds. Between milestones the version is 3.0.0-SNAPSHOT, and 3.0.0 is not released (see How a release is made).

Where things are

File What it holds
pom.xml (root) Parent and aggregator, io.descoped.lds:linked-data-store-project. The list of modules, the JDK, the version of every dependency (properties), the version and the rules of the plugins (pluginManagement), the profiles, and the enforcer plugin with its rules (<build><plugins>).
linked-data-store-bom/pom.xml The BOM. It manages the versions of the LDS modules and nothing else.
<module>/pom.xml The dependencies of the module, and the exceptions from the lint and Javadoc rules that the module still has.
<module>/src/main/java/module-info.java The module descriptor. Every module with code has one, except the TCK.
mvnw, mvnw.cmd, .mvn/wrapper/maven-wrapper.properties The Maven wrapper: which Maven is used, and the checksum of its download.
.github/workflows/ci.yml The build in GitHub Actions.
.github/workflows/claude.yml The review of a pull request by Claude, and its answer to an @claude mention. It builds nothing by itself.
.github/workflows/pages.yml The build of the documentation site and its publication to GitHub Pages.
.github/renovate.json What Renovate moves, and the versions it is told to leave.
site/ The documentation site.
.gitignore, .gitattributes Build output, local configuration and release leftovers are ignored. Every text file is checked out with LF line ends, so that a checkout on any system makes the same sources jar.

The modules

The reactor has the root and ten modules, 11 projects in all. Maven builds the root first and then the modules in an order that follows their dependencies. <modules> in the root POM is written in that order, so the build order is the order of <modules> and of this table.

Maven module JPMS module LDS modules it depends on
linked-data-store-bom none (packaging pom) none
linked-data-store-persistence-provider-api io.descoped.lds.persistence.api none
linked-data-store-persistence-provider-tck none (class path) persistence API
linked-data-store-persistence-provider-memory io.descoped.lds.persistence.memory persistence API; TCK (test)
linked-data-store-persistence-provider-neo4j io.descoped.lds.persistence.neo4j persistence API; TCK (test)
linked-data-store-persistence-provider-postgres io.descoped.lds.persistence.postgres persistence API; TCK (test)
linked-data-store-search-provider-api io.descoped.lds.search.api persistence API
linked-data-store-search-provider-solr io.descoped.lds.search.provider.solr search API, persistence API
linked-data-store-core io.descoped.lds.core persistence API, search API; memory provider (test)
linked-data-store-server io.descoped.lds.server core; the memory, Neo4j and PostgreSQL providers and the Solr provider (runtime)

Of the LDS modules, core depends on the two interfaces only. It does not depend on a provider, except on the memory provider for its tests. The server module is the one place where core and every provider meet: its POM names the providers with scope runtime, and also the saga log in PostgreSQL (no.cantara.saga:sagalog-postgres) and the transaction log in PostgreSQL (io.descoped.rawdata:rawdata-client-provider-postgres).

The TCK, the shared suite of the persistence providers, holds its test classes in src/main/java, because the tests are what the module is made for. A provider depends on it with scope test and extends PersistenceIntegrationTest. The TCK names TestNG, AssertJ, JSONassert, slf4j-api and logback-classic without a scope, so a provider gets them for its tests through the TCK. The TCK POM tells SonarCloud to read src/main/java as tests (sonar.tests) and only pom.xml as sources (sonar.sources).

The module descriptors

JPMS module Requires Exports Services
io.descoped.lds.persistence.api transitive io.reactivex.rxjava3, transitive tools.jackson.databind, tools.jackson.core io.descoped.lds.api.persistence and its packages flattened, streaming, json, reactivex; io.descoped.lds.api.specification; io.descoped.lds.api.json none
io.descoped.lds.search.api transitive io.descoped.lds.persistence.api, transitive io.reactivex.rxjava3, Jackson io.descoped.lds.api.search none
io.descoped.lds.persistence.memory persistence API, io.descoped.tuple, RxJava nothing provides PersistenceInitializer with MemoryInitializer
io.descoped.lds.persistence.neo4j persistence API, Jackson, org.neo4j.driver, java.logging, jul.to.slf4j, org.slf4j, RxJava nothing provides PersistenceInitializer with Neo4jInitializer
io.descoped.lds.persistence.postgres persistence API, java.sql, com.zaxxer.hikari, org.postgresql.jdbc, java.logging, jul.to.slf4j, RxJava nothing provides PersistenceInitializer with PostgresDbInitializer
io.descoped.lds.search.provider.solr search API, persistence API, solr.solrj, org.slf4j, RxJava nothing provides SearchIndexProvider with SolrProvider
io.descoped.lds.core the two interfaces, dynamic-configuration, the saga libraries, io.descoped.rawdata.api, Undertow and XNIO, graphql-java and its extended scalars, Jackson and its MessagePack format, com.networknt.schema, Tika, RxJava, org.slf4j, java.net.http, java.xml, jdk.unsupported io.descoped.lds.core, io.descoped.lds.test.server uses PersistenceInitializer, SearchIndexProvider and SagaLogInitializer; provides SearchIndexProvider with TestSearchIndex; opens io.descoped.lds.graphql.graphiql
io.descoped.lds.server io.descoped.lds.core, io.descoped.dynamic.config, org.slf4j, org.apache.commons.logging nothing none

A provider exports nothing: core finds it as a service and uses it through the interface. The packages of the providers are named io.descoped.lds.core.persistence.<name> and io.descoped.lds.core.search.solr, although they are not in core.

The descriptor of a built jar can be read with the jar tool. Here it is run in a folder that has every jar in lib, as linked-data-store-server/target has after a build:

Shell
jar --describe-module --file lib/linked-data-store-search-provider-solr-3.0.0-SNAPSHOT.jar
Text
io.descoped.lds.search.provider.solr@3.0.0-SNAPSHOT jar:file:///.../module-info.class
requires io.descoped.lds.persistence.api
requires io.descoped.lds.search.api
requires io.reactivex.rxjava3
requires java.base mandated
requires org.slf4j
requires solr.solrj
provides io.descoped.lds.api.search.SearchIndexProvider with io.descoped.lds.core.search.solr.SolrProvider
contains io.descoped.lds.core.search.solr

What a build does, in order

What comes in is the sources and the libraries Maven fetches: from Maven Central, and from the release repository of Cantara (cantara-releases in the root POM) for the saga libraries, which are not on Maven Central.

For each module, in reactor order:

  1. enforcer:enforce checks the JDK and Maven (see JDK 27). The root and the BOM have packaging pom: for them this is the only step, apart from the last.
  2. The resources are copied and the main code is compiled, as a named module where there is a module-info.java, with the lint rule (see Every compiler warning is an error).
  3. The test code is compiled with the same compiler arguments.
  4. Surefire runs the tests on the class path (see How the tests run).
  5. The jar is made. Every entry of it has the time in project.build.outputTimestamp of the root POM, so the same sources give the same bytes.
  6. In the server module only: before the jar is made, the jars of an earlier build are removed (target/*.jar and target/lib); after it, every library LDS runs with is copied to target/lib (copy-dependencies, scope runtime); then Failsafe runs the tests of the image (*IT).
  7. javadoc:javadoc, when it is named on the command line as CI does, checks the Javadoc (see Javadoc). The goal runs the build up to generate-sources once more before it starts, so the log shows enforcer:enforce twice for each module.

What goes out is one jar for each module in its target folder, and in linked-data-store-server/target the jar of the server and the folder lib. Those two are what the image is made of; see the server and its image. The jar of the server has no Main-Class, so LDS is started with the class path and the name of the main class. With every jar in one folder lib, as the image has them:

Shell
LDS_HTTP_PORT=19113 java -cp "lib/*" io.descoped.lds.server.Server
curl -i http://127.0.0.1:19113/ping
HTTP
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 0
Date: Fri, 20 Nov 2026 15:31:41 GMT

These are the commands of the build. ./mvnw verify javadoc:javadoc is what CI runs, and it needs Docker and JDK 27. The commands were not run for this document, and their output is not shown.

Shell
./mvnw verify javadoc:javadoc                  # what CI runs: build, tests, Javadoc
./mvnw package -DskipTests                     # the jars, without running the tests
./mvnw verify -pl linked-data-store-core -am   # one module and what it needs
./mvnw test -pl linked-data-store-core -Dtest=DataControllerTest
./mvnw verify -P coverage                      # with JaCoCo reports
# the tests of the image only:
./mvnw verify -pl linked-data-store-server -am -Dtest=None -Dsurefire.failIfNoSpecifiedTests=false

The rules of the build

The rules are those of the project (see the invariants) and those of the comments in the POMs. Keep them when changing the build.

One reactor, one version

Every module has the root POM as its parent and takes its version from it. A module depends on another LDS module with ${project.version}. The release plugin is told to give every module the same version (autoVersionSubmodules). Do not give a module a version of its own: the modules are made to be released together.

The modules also share the address of the project. The root POM switches off Maven's habit of adding the artifactId of a module to the inherited url and scm (child.project.url.inherit.append.path="false" and the three child.scm... attributes), because the modules are folders of one repository.

Dependency versions are properties

The version of every library is a property in the root POM (jackson.version, testcontainers.version, ...), and each module writes <version>${jackson.version}</version> where it uses the library. The root POM has no dependencyManagement. This is on purpose: the BOM inherits the root POM, and anything in the dependencyManagement of the root would become part of the BOM. No module POM has a version number written in it, apart from the version of the parent.

The versions of the plugins are in pluginManagement of the root POM. Two kinds of plugin have their version where they are used: the enforcer plugin, in <build><plugins> of the root POM, and the plugins that only a profile uses (JaCoCo, the Sonar scanner, the source, GPG and Central publishing plugins), in that profile.

The BOM

linked-data-store-bom manages nine artifacts, all with ${project.version}: the persistence API, the TCK, the three persistence providers, the search API, the Solr provider, core and the server. It manages no library of another project. A new module is added to <modules> of the root POM and to the BOM.

JDK 27

LDS is built, tested and run on JDK 27. The number is written in these places, and they are changed together:

Where What
root pom.xml, java.version Gives maven.compiler.release, so the class files are for Java 27 (class file version 71), and the version the enforcer rule requireJavaVersion asks for.
.github/workflows/ci.yml actions/setup-java with java-version: '27', distribution temurin.
.github/workflows/claude.yml The same, in the job respond, which may run the build.
linked-data-store-server/Dockerfile FROM eclipse-temurin:27-jre-alpine.
.github/renovate.json Two rules that stop Renovate from raising the JDK of the workflows and of the image.

The enforcer rule gives the lowest JDK: a newer JDK passes it too, and the compiler then still writes class files for Java 27. The same execution asks for Maven from 3.6.3 and below 4, because the plugin that publishes to Maven Central does not support Maven 4.

Every compiler warning is an error

The root POM gives the compiler -Xlint:all -Werror. A module that has not been revised for 3.0 replaces these arguments (combine.self="override") with a list that names the categories it is not clean of. When a module is revised, its exception is removed. An exception is never made wider.

Module Categories that are switched off
persistence API requires-automatic, exports, serial, missing-explicit-ctor, rawtypes, deprecation
TCK deprecation, this-escape
search API requires-automatic, exports
Solr provider requires-automatic
core requires-automatic, exports, serial, missing-explicit-ctor, rawtypes, unchecked, cast, deprecation, lossy-conversions, static
memory, Neo4j, PostgreSQL, server none: the rule of the root POM holds

The PostgreSQL provider has one exception in its code and not in its POM: its module-info.java has @SuppressWarnings("requires-automatic"), because the JDBC driver of PostgreSQL is an automatic module.

Not finished: some of the categories that are switched off give no warning any more. Compiling these modules with javac --release 27 -Xlint:all, the main sources as a module with the jars LDS runs with on the module path and the test sources on the class path, gives these warnings in the categories of the lint rule:

Module Warnings Switched off, but no warning
persistence API missing-explicit-ctor 5, rawtypes 1, serial 1 requires-automatic, exports, deprecation
TCK deprecation 6, this-escape 1 none
search API none requires-automatic, exports
Solr provider requires-automatic 1 (solr.solrj) none
core deprecation 25, exports 15, unchecked 15, rawtypes 7, requires-automatic 6, serial 3, missing-explicit-ctor 1, lossy-conversions 1, static 1 cast

This was measured with javac and not with Maven. Remove a category from a POM only after a build with Maven passes without it.

The six automatic modules that core requires are undertow.core, xnio.api, jackson.dataformat.msgpack, org.apache.tika.core, com.graphqljava and com.graphqljava.extendedscalars.

Not finished: the first three of them, and solr.solrj of the Solr provider, have no Automatic-Module-Name in the manifest of their jar, so the name of the module is made from the name of the jar file. The compiler plugin of Maven says so in every build, as a warning for core and as a line of information for the Solr provider and for the server:

Text
Required filename-based automodules detected: [jackson-dataformat-msgpack-3.0.0.jar, undertow-core-2.4.4.Final.jar,
xnio-api-3.8.17.Final.jar]. Please don't publish this project to a public artifact repository!

For the Solr provider the jar is solr-solrj-10.1.0.jar. The message does not fail the build. The message is shown here on two lines; Maven writes it on one.

Javadoc

The root POM gives the Javadoc plugin doclint all and failOnWarnings true: every public element has Javadoc, and a fault in it fails the build. Six modules still replace doclint with all,-missing, which checks the Javadoc that is there and does not ask for what is missing: the persistence API, the TCK, the memory provider, the search API, the Solr provider and core. The Neo4j provider, the PostgreSQL provider and the server follow the rule of the root.

Javadoc is not part of verify. It runs when javadoc:javadoc is named, as CI does, and when the profile central makes the Javadoc jar. detectOfflineLinks is false: the Javadoc of the modules is not published anywhere, and javadoc warns when a module on the class path (the TCK) links to a named module.

JPMS

  • Every LDS module with code is a named module, except the TCK, which has no module-info.java.
  • A module whose exported API shows the types of another module requires transitive it. The persistence API does so for RxJava and tools.jackson.databind, the search API for the persistence API and RxJava.
  • A provider is registered twice: with provides in module-info.java, and with a file in META-INF/services. Both are needed. LDS runs on the class path, in the tests and in the image, and there only the file in META-INF/services is read. The provides line is checked by the compiler.
  • uses is declared by core, which is the module that calls ServiceLoader (PersistenceConfigurator, SearchIndexConfigurator, UndertowApplication). The two modules that define the interfaces declare no uses. The rule of the project is worded the other way: the module that defines a service interface declares uses for it. The code and the rule do not agree.
  • The module descriptors are checked when the modules are compiled, and nowhere else: nothing in the build runs LDS on the module path.

Not finished: the descriptor of core has three things that are there for tests.

  • It provides SearchIndexProvider with TestSearchIndex, a class in src/main/java. The file in META-INF/services that names it is in the test resources of core, so the jar of core does not have it.
  • It exports io.descoped.lds.test.server. In src/main/java that package holds the empty class Dummy; the classes that matter (TestServer, TestServerListener) are in src/test/java. The comment says the export is needed to run tests in IntelliJ.
  • It has requires java.xml with the comment TODO this should be in test-scope only!. No class of core, in the main code or in the tests, names a type of java.xml.

Libraries that are left out or pinned in core

The POM of core leaves these out of what its libraries bring: reactive-streams from dynamic-configuration, okhttp from graphql-java-extended-scalars, jackson-dataformat-yaml from the JSON Schema validator (LDS reads no schema written as YAML), and jboss-threads, wildfly-common and jboss-logging from xnio-api. It names jboss-threads itself, with a version of its own (jboss-threads.version) and again without jboss-logging, and xnio-nio, both with scope runtime. Only the YAML exclusion has its reason written in the POM.

Other rules that show in the build

  • Always the latest stable version of every library, plugin, action, image and engine. Renovate moves them, and CI is the gate (see Renovate).
  • No secret but the documented development defaults of the tests and the compose file.
  • CI publishes nothing, and a release is made by hand (see How a release is made).

The profiles

Profile What it does
coverage Runs the tests with the JaCoCo agent (prepare-agent) and writes the report of each module in the phase prepare-package. The tests of the image run after that phase and are not in the report.
sonar Sets the address, the organisation (descoped) and the project key (descoped_linked-data-store-project) of SonarCloud, and the version of the scanner. There is one SonarCloud project for the whole reactor. The scanner runs only when its goal is named, as CI does.
central For a release: attaches a sources jar and a Javadoc jar to every module, and adds central-publishing-maven-plugin, which uploads to the Central Portal as server central, waits until the upload is validated, and does not publish it (autoPublish false).
sign For a release: signs every artifact with GPG in the phase verify, with the default key of gpg.

No profile is active by default.

The Maven wrapper

./mvnw is a script and nothing else (distributionType=only-script): no jar of the wrapper is in the repository. On first use it downloads the Maven named in .mvn/wrapper/maven-wrapper.properties, now 3.10.1, compares the download with distributionSha256Sum, and unpacks it under ~/.m2/wrapper/dists. If the checksum differs, the script stops. CI runs ./mvnw. The folder .mvn holds nothing but the properties of the wrapper.

The checksum in the file is the SHA-256 of the zip that distributionUrl names:

Shell
curl -sS -f -L -o apache-maven-3.10.1-bin.zip \
  https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.10.1/apache-maven-3.10.1-bin.zip
shasum -a 256 apache-maven-3.10.1-bin.zip
Text
9c1ef9174ef250a5009ed0dec97cbe8699acf7479add4e62bf7b0ea791c0adb5  apache-maven-3.10.1-bin.zip

When Maven is raised, by Renovate or by hand, Renovate does not change the checksum, and the wrapper refuses the new download until it is set. Set distributionSha256Sum to the SHA-256 of the new apache-maven-<version>-bin.zip, after comparing that zip with the .sha512 that Maven publishes next to it. A Maven 4 does not pass the enforcer rule.

How the tests run

Two frameworks, one run

New and revised tests are JUnit 6 with AssertJ. The older tests are TestNG 7. Surefire 3.6.1 runs both on the JUnit Platform: it picks its provider for the platform, and when TestNG is on the class path it adds the TestNG engine for the platform by itself. A module needs no configuration for this; it names junit-jupiter, testng or both as test dependencies. The log of a build shows it:

Text
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] TestNG is present. Adding per default org.junit.support:testng-engine:1.1.0

No POM names testng-engine. Its version is the one Surefire picks, and no property of the root POM sets it.

A class that extends the shared suite (PersistenceIntegrationTest) or the Reactive Streams TCK stays TestNG, because those are. In core, a test that takes its server from TestServerListener is TestNG; a new test class that starts a server of its own is JUnit.

On the class path

useModulePath is false for Surefire and Failsafe in the root POM. The tests are in the same packages as the code they test, and they run on the class path together with it. So a test finds a provider through META-INF/services, not through module-info.java.

Surefire and Failsafe

Surefire runs the classes it finds by its default name patterns (*Test, which *IntegrationTest also matches) in the phase test. Failsafe is set up in the server module only. It runs ServerImageIT and ServerStackIT after the jars are made, so verify runs them and test and package do not.

Surefire finds no test to run in three modules: the TCK (its suite is an abstract class in src/main/java, and it runs in the providers), the search API (it has no tests) and the server (its tests are the *IT classes).

Containers

The tests run on the real engines, in containers that Testcontainers starts. The build needs Docker, and for the server module also the docker command with compose.

Module Image Named in
PostgreSQL provider postgres:18-alpine Postgres18
Neo4j provider neo4j:2026.10-community Neo4j2026
Solr provider solr:10.1 Solr10
core postgres:18-alpine SagaLogPostgresTest
server the image built from the Dockerfile; the images of compose.yaml ServerImageIT, ServerStackIT

In the provider modules one container serves every test class of the module. It is started on first use and removed by Testcontainers when the JVM ends. In core, SagaLogPostgresTest starts a container for itself before its tests and stops it after them.

LoopbackPorts

Each module that starts a container has a class LoopbackPorts in its tests, and a file META-INF/services/org.testcontainers.core.CreateContainerCmdModifier in its test resources that names it. There are five: in the PostgreSQL provider, the Neo4j provider, the Solr provider, core and the server. The five classes are the same but for the package.

Testcontainers calls LoopbackPorts.modify for every container it creates, also the one it starts for itself to clean up (Ryuk). The method changes each port that is published without an address to be published on 127.0.0.1. Without it a port is published on every address of the machine, and on macOS Docker Desktop can then pick a port that another program listens on at 127.0.0.1. The test reaches that program and not the container, and the build fails with "Could not connect to Ryuk" or with an engine that never answers.

The code that starts a container calls LoopbackPorts.check on it. The check fails with a message that names the file in META-INF/services when a port is published on another address. A new module that starts containers needs its own copy of the class and of the file.

The server of the tests in core

The tests of core start LDS in the JVM with the memory provider (TestServerListener), one LDS for each configuration the tests ask for. The port is picked at random between 9000 and 9499. A port is taken only when it is free in two ways: on every address of the machine, and on 127.0.0.1 alone (TestServerListener.findFreePort).

Tests that are disabled

13 tests in core are disabled in the source. They are TestNG tests, and the build does not count them, not as run and not as skipped.

Class Disabled
DataControllerTest testGetEmptyDomainList, testPutDomain, testGetDomainList, testGetDomain, testGetMissingDomain (enabled = false)
NamespaceControllerTest thatPUTOnLegalNamespaceAndDocumentAcceptsWith200 (enabled = false)
ResourceContextIntegrationTest thatFreakyResourceURLsAreDecodedProperly (@Ignore)
PersistenceLinksConnectionFetcherTest testForwardPagination, testBackwardPagination (@Ignore; the comment says the method hangs)
PersistenceRootConnectionFetcherTest the whole class, four tests (@Ignore; the comment says the tests hang)

The two test classes of the Reactive Streams TCK (AsyncIterablePublisherTest in the memory provider, ResultSetPublisherIntegrationTest in the PostgreSQL provider) each report 11 of their 38 tests as skipped. Those are not disabled in the source of LDS.

A change that switches tests on is run about ten times before it is pushed:

Shell
for n in $(seq 1 10); do ./mvnw -B -q verify || break; done

CI

.github/workflows/ci.yml has one job, Build (JDK 27), on ubuntu-latest with a limit of 30 minutes.

It runs on:

  • a push to master;
  • a push of a tag of the form 1.2.3;
  • a pull request to master;
  • a start by hand (workflow_dispatch), on any branch.

A push or a pull request starts it only when it changes what can change the products: the root pom.xml, mvnw, .mvn/, a file in a module folder (linked-data-store-*/) that is not a Markdown file, or ci.yml itself. A change of the documentation (docs/, README.md, any Markdown file), LICENSE, .claude/, claude.yml, renovate.json or .gitignore alone does not start it. A tag starts it whatever it changes. A newer push to the same pull request or branch ends the run that is in progress.

The job checks out the code, sets up JDK 27 (Temurin) with the Maven cache, and runs one of two commands:

When Command
a pull request from a fork, or a start by hand ./mvnw --batch-mode --no-transfer-progress verify javadoc:javadoc
a push, or a pull request from this repository the same with -P coverage, then the SonarCloud scanner with -P sonar

The SonarCloud step is not a gate: it has continue-on-error, so a fault of SonarCloud or of its token (the secret SONARCLOUD_TOKEN) does not fail the build. A pull request from a fork gets no secrets, so it gets no analysis. The checkout fetches the whole history only when the analysis runs.

The job has the permission contents: read and no step that deploys, pushes or uploads. CI publishes no SNAPSHOT, no release and no image.

The actions are pinned by commit, with the version in a comment. Renovate moves them.

.github/workflows/claude.yml has two jobs. review reads a pull request when it is opened or reopened and posts one review; it does not run the tests, and its token cannot change the code. It reviews Markdown files and docs/ too, and is not started by a pull request that changes nothing but LICENSE, .claude/, claude.yml, renovate.json or .gitignore. respond answers an @claude mention from the owner, a member or a collaborator, in a pull request or an issue, and may run ./mvnw ... verify or package on JDK 27 before it pushes a fix. Both jobs need the secret CLAUDE_CODE_OAUTH_TOKEN.

Renovate

.github/renovate.json extends config:recommended and has the dependency dashboard.

Rule What it does
managers maven and github-actions Updates are merged by themselves (automerge); the description of the rule says that CI is the gate. The rule names these two managers only, so it does not hold for the images of the Dockerfile and of compose.yaml.
java-jdk in the workflows Switched off. The JDK of the workflows is raised by hand.
image eclipse-temurin Only versions that start with 27.
image postgres Only versions that start with 18.
manager maven-wrapper The pull request gets the label maven-wrapper and a note that says to set distributionSha256Sum by hand.
vulnerability alerts Label security, merged by themselves.

Two versions are held on purpose:

  • JDK 27, the baseline. It is raised in java.version, the workflows and the image together.
  • PostgreSQL 18, by the owner's decision. The owner says when it is raised.

The rule for postgres is about the image. The JDBC driver of PostgreSQL (postgresql.version) is a Maven dependency and moves like the others.

The images of the tests are also written as text in Java classes (Postgres18, Neo4j2026, Solr10, SagaLogPostgresTest). renovate.json sets up no manager that reads Java sources. The rule is that the compose file uses the images the tests of the providers use, so compare the two by hand when one of them moves.

The documentation site

The documents in docs/ are also a site, which GitHub Pages serves at https://lds.descoped.io/, with a landing page in front of them. The site is in site/, outside the reactor: a static site made with krantho and Next.js, which Maven does not build. site/README.md says how to build it and where each page comes from.

lds.descoped.io is the custom domain of the repository's Pages, set in its settings, with HTTPS enforced. Its DNS record, a CNAME to descoped.github.io, is kept outside this repository. The site is on the root of the domain, and GitHub forwards descoped.github.io/linked-data-store-project/ to it.

.github/workflows/pages.yml builds the site with pnpm on Node 26 and publishes it to Pages on a push to master that changes docs/, site/ or the workflow, and on a start by hand. It has two jobs: build, with the permission contents: read, and deploy, with pages: write and id-token: write, which only GitHub Pages is given.

Each document starts with front matter that the site reads: title, description and order. GitHub shows it as a table at the top of the file.

How a release is made

A milestone and a release are both made by hand, with the owner's go-ahead for each one.

A milestone

A milestone, such as 3.0.0-M1, is a tag of the source and a release on GitHub with its notes. Nothing is built for it and nothing is published: no jar, no image, nothing on Maven Central. It is made with two pull requests and a tag:

  1. The first sets the version of every POM to the milestone, sets project.build.outputTimestamp in the root POM to the time of the milestone, sets softwareVersion in site/krantho.config.ts, and adds the milestone's notes to RELEASE-NOTES.md, in a section of its own, with links that are whole addresses so they also lead somewhere in the release on GitHub. CI builds and tests it, as any pull request that changes code.

  2. Its commit on master is tagged with the version alone (3.0.0-M1), and the release on GitHub is made from the tag with the milestone's section of the notes, without its heading:

    Shell
    git tag -a 3.0.0-M1 -m 3.0.0-M1 && git push origin 3.0.0-M1
    awk '/^## 3.0.0-M1$/{f=1;next} /^## /{f=0} f' RELEASE-NOTES.md > notes.md
    gh release create 3.0.0-M1 --prerelease --title "LDS 3.0.0-M1" --notes-file notes.md
  3. The second pull request sets the versions back to 3.0.0-SNAPSHOT.

The push of a milestone's tag does not start CI: its tags are of the form 1.2.3 only.

A release

Not finished: no release has been made with the command below, and the repository has no tag of the form 1.2.3, which is the form the release plugin is told to use. It is the command the comment in the root POM gives.

Shell
./mvnw release:prepare release:perform
  • The release plugin gives every module the same version, tags the commit with the version alone (3.0.0), and runs deploy with the profiles central and sign.
  • The comment in the root POM says that release:prepare sets project.build.outputTimestamp to the time of the release.
  • The upload goes to the Central Portal and stays there, validated and unpublished. It is published by hand in the Portal.
  • The server central in ~/.m2/settings.xml holds the token of the Portal. The comment in the root POM says that for Maven 3.10 it also lists https://central.sonatype.com in repositoryOrigins.
  • SNAPSHOT versions are not published.
  • The push of the tag starts CI, which builds and tests and publishes nothing.
  • .gitignore has the files an interrupted release leaves (release.properties, pom.xml.releaseBackup, ...).

Nothing in the repository publishes the image of the server.

Not finished

  • 3.0.0 is not released, and nothing is published.
  • The TCK is not a named module.
  • Six modules have an exception from the Javadoc rule and five from the lint rule; some of the lint categories that are switched off give no warning any more (see Every compiler warning is an error).
  • The descriptor of core provides a class that is for tests, exports a package that is for tests, and requires java.xml, which no class of core uses (see JPMS above).
  • The JPMS rule of the project says that the module that defines a service interface declares uses for it. In the code core declares uses, and the two modules that define the interfaces do not.
  • Core and the Solr provider require automatic modules whose names are made from the names of jar files, and Maven warns against publishing such a project (see Every compiler warning is an error).
  • 13 tests in core are disabled.
  • The search API declares testng, assertj-core and jsonassert as test dependencies and has no tests. Core declares commons-math3 as a test dependency, and no class uses it.
  • The root POM has a repository of its own for the saga libraries. Its comment says the repository goes when core stops using them.