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:
jar --describe-module --file lib/linked-data-store-search-provider-solr-3.0.0-SNAPSHOT.jario.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.solrWhat 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:
enforcer:enforcechecks the JDK and Maven (see JDK 27). The root and the BOM have packagingpom: for them this is the only step, apart from the last.- 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). - The test code is compiled with the same compiler arguments.
- Surefire runs the tests on the class path (see How the tests run).
- The jar is made. Every entry of it has the time in
project.build.outputTimestampof the root POM, so the same sources give the same bytes. - In the server module only: before the jar is made, the jars of an earlier build are removed (
target/*.jarandtarget/lib); after it, every library LDS runs with is copied totarget/lib(copy-dependencies, scoperuntime); then Failsafe runs the tests of the image (*IT). javadoc:javadoc, when it is named on the command line as CI does, checks the Javadoc (see Javadoc). The goal runs the build up togenerate-sourcesonce more before it starts, so the log showsenforcer:enforcetwice 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:
LDS_HTTP_PORT=19113 java -cp "lib/*" io.descoped.lds.server.Server
curl -i http://127.0.0.1:19113/pingHTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 0
Date: Fri, 20 Nov 2026 15:31:41 GMTThese 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.
./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=falseThe 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:
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 transitiveit. The persistence API does so for RxJava andtools.jackson.databind, the search API for the persistence API and RxJava. - A provider is registered twice: with
providesinmodule-info.java, and with a file inMETA-INF/services. Both are needed. LDS runs on the class path, in the tests and in the image, and there only the file inMETA-INF/servicesis read. Theprovidesline is checked by the compiler. usesis declared by core, which is the module that callsServiceLoader(PersistenceConfigurator,SearchIndexConfigurator,UndertowApplication). The two modules that define the interfaces declare nouses. The rule of the project is worded the other way: the module that defines a service interface declaresusesfor 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
SearchIndexProviderwithTestSearchIndex, a class insrc/main/java. The file inMETA-INF/servicesthat 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. Insrc/main/javathat package holds the empty classDummy; the classes that matter (TestServer,TestServerListener) are insrc/test/java. The comment says the export is needed to run tests in IntelliJ. - It has
requires java.xmlwith the commentTODO this should be in test-scope only!. No class of core, in the main code or in the tests, names a type ofjava.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:
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.zip9c1ef9174ef250a5009ed0dec97cbe8699acf7479add4e62bf7b0ea791c0adb5 apache-maven-3.10.1-bin.zipWhen 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:
[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.0No 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:
for n in $(seq 1 10); do ./mvnw -B -q verify || break; doneCI
.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:
The first sets the version of every POM to the milestone, sets
project.build.outputTimestampin the root POM to the time of the milestone, setssoftwareVersioninsite/krantho.config.ts, and adds the milestone's notes toRELEASE-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.Its commit on
masteris 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:Shellgit 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.mdThe 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.
./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 runsdeploywith the profilescentralandsign. - The comment in the root POM says that
release:preparesetsproject.build.outputTimestampto 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
centralin~/.m2/settings.xmlholds the token of the Portal. The comment in the root POM says that for Maven 3.10 it also listshttps://central.sonatype.cominrepositoryOrigins. - SNAPSHOT versions are not published.
- The push of the tag starts CI, which builds and tests and publishes nothing.
.gitignorehas 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
usesfor it. In the code core declaresuses, 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-coreandjsonassertas test dependencies and has no tests. Core declarescommons-math3as 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.