refactoring/separate_deployable_pom (#460)

redcatbear · web-flow · commit 5a7f1a45fe0e · 2025-06-14T16:52:22.000+02:00
* Attempt to distinguish between deployable and non-deployable parts with two parent POMs.
* Fixed review findings and added developer documentation.
* Updated release date.
diff --git a/api/pom.xml b/api/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-api</artifactId>
     <name>OpenFastTrace API</name>
     <parent>
-        <relativePath>../parent/pom.xml</relativePath>
+        <relativePath>../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/core/pom.xml b/core/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-core</artifactId>
     <name>OpenFastTrace Core</name>
     <parent>
-        <relativePath>../parent/pom.xml</relativePath>
+        <relativePath>../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/doc/changes/changes_4.2.0.md b/doc/changes/changes_4.2.0.md
@@ -1,4 +1,4 @@
-# OpenFastTrace 4.2.0, released 2025-06-13
+# OpenFastTrace 4.2.0, released 2025-06-14
 
 Code name: Markdown code blocks
 
diff --git a/doc/developer_guide.md b/doc/developer_guide.md
@@ -33,10 +33,10 @@ dependencies {
 
 ## Build Time Dependencies
 
-The list below shows all build time dependencies in alphabetical order. Note that except the Maven build tool all required modules are downloaded automatically by Maven.
+The list below shows all build time dependencies in alphabetical order. Note that except the Maven build tool, Maven downloads all required modules automatically.
 
 | Dependency                                                                         | Purpose                                                | License                       |
-| ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- |
+|------------------------------------------------------------------------------------|--------------------------------------------------------|-------------------------------|
 | [Apache Maven](https://maven.apache.org/)                                          | Build tool                                             | Apache License 2.0            |
 | [Equals Verifier](https://github.com/jqno/equalsverifier)                          | Automatic contract checker for `equals()` and `hash()` | Apache License 2.0            |
 | [Hamcrest Auto Matcher](https://github.com/itsallcode/hamcrest-auto-matcher)       | Speed-up for building Hamcrest matchers                | GNU General Public License V3 |
@@ -46,7 +46,7 @@ The list below shows all build time dependencies in alphabetical order. Note tha
 
 ## Preparations
 
-OpenFastTrace uses [Apache Maven](https://maven.apache.org) as technical project management tool that resolves and downloads the build-dependencies before building the packages.
+OpenFastTrace uses [Apache Maven](https://maven.apache.org) as the technical project management tool that resolves and downloads the build-dependencies before building the packages.
 
 ### Installation of Initial Build Dependencies on Linux
 
@@ -126,7 +126,7 @@ To build and test with a later version, add argument `-Djava.version=17` to the
 
 By default, Maven builds the OFT modules sequentially.
 
-To speedup the build and build modules in parallel, add argument `-T 1C` to the Maven command.
+To speed up the build and build modules in parallel, add argument `-T 1C` to the Maven command.
 
 ### Run Requirements Tracing
 
@@ -140,7 +140,7 @@ Import as a Maven project using *"File" &rarr; "Import..." &rarr; "Maven" &rarr;
 
 ## Configure the `itsallcode style` formatter
 
-All sub-projects come with formatter and save actions configuration for Eclipse.
+All subprojects come with formatter and save actions configuration for Eclipse.
 
 If you use a different IDE like IntelliJ, please import the formatter configuration [itsallcode_formatter.xml](itsallcode_formatter.xml).
 
@@ -183,7 +183,7 @@ This project is configured to produce exactly the same artifacts each time when
   ```bash
   mvn initialize artifact:check-buildplan
   ```
-* Verify that the build produces excatly the same artifacts:
+* Verify that the build produces exactly the same artifacts:
   ```bash
   mvn -T 1C clean install -DskipTests
   mvn -T 1C clean verify artifact:compare -DskipTests
@@ -199,18 +199,64 @@ The build will use the last Git commit timestamp as timestamp for files in `.jar
 
 1. Checkout the `main` branch.
 2. Create a new "prepare-release" branch.
-3. Update version in
+3. Update the version in
     * `openfasttrace-parent/pom.xml` (`revision` property)
     * `README.md`
     * `doc/developer_guide.md`
-4. Add changes in new version to `doc/changes/changes.md` and `doc/changes/changes_$VERSION.md` and update the release date.
+4. Add changes in a new version to `doc/changes/changes.md` and `doc/changes/changes_$VERSION.md` and update the release date.
 5. Commit and push changes.
 6. Create a new pull request, have it reviewed and merged to `main`.
 
 ### Perform the Release
 
 1. Start the release workflow
-  * Run command `gh workflow run release.yml --repo itsallcode/openfasttrace --ref main`
-  * or go to [GitHub Actions](https://github.com/itsallcode/openfasttrace/actions/workflows/release.yml) and start the `release.yml` workflow on branch `main`.
-2. Update title and description of the newly created [GitHub release](https://github.com/itsallcode/openfasttrace/releases).
+   * Run command `gh workflow run release.yml --repo itsallcode/openfasttrace --ref main`
+   * or go to [GitHub Actions](https://github.com/itsallcode/openfasttrace/actions/workflows/release.yml) and start the `release.yml` workflow on branch `main`.
+2. Update the title and description of the newly created [GitHub release](https://github.com/itsallcode/openfasttrace/releases).
 3. After some time the release will be available at [Maven Central](https://repo1.maven.org/maven2/org/itsallcode/openfasttrace/openfasttrace/).
+
+## Module Overview
+
+This section explains the module structure of OpenFastTrace.
+
+| Module                                     | Deployed to MC | Content                                                  |
+|--------------------------------------------|----------------|----------------------------------------------------------|
+| **Core Modules**                           |                |                                                          |
+| `openfasttrace-api`                        | ✅              | Core API interfaces and contracts for the tracing system |
+| `openfasttrace-core`                       | ✅              | Main implementation of tracing logic and algorithms      |
+| `openfasttrace-testutil`                   | ❌              | Test utilities and helpers (internal development only)   |
+| **Exporters**                              |                |                                                          |
+| `openfasttrace-exporter-common`            | ✅              | Common utilities and base classes for exporters          |
+| `openfasttrace-exporter-specobject`        | ✅              | Exporter for SpecObject format                           |
+| **Importers**                              |                |                                                          |
+| `openfasttrace-importer-lightweightmarkup` | ✅              | Base classes for lightweight markup importers            |
+| `openfasttrace-importer-markdown`          | ✅              | Importer for Markdown documents with requirement tags    |
+| `openfasttrace-importer-restructuredtext`  | ✅              | Importer for reStructuredText documents                  |
+| `openfasttrace-importer-specobject`        | ✅              | Importer for SpecObject XML format                       |
+| `openfasttrace-importer-tag`               | ✅              | Importer for tagged source code comments                 |
+| `openfasttrace-importer-xmlparser`         | ✅              | Common XML parsing utilities for importers               |
+| `openfasttrace-importer-zip`               | ✅              | Importer for ZIP archives containing requirements        |
+| **Reporters**                              |                |                                                          |
+| `openfasttrace-reporter-plaintext`         | ✅              | Plain text report generator                              |
+| `openfasttrace-reporter-html`              | ✅              | HTML report generator with interactive features          |
+| `openfasttrace-reporter-aspec`             | ✅              | ASpec format reporter for augmented specifications       |
+| **Product**                                |                |                                                          |
+| `openfasttrace` (product)                  | ✅              | Complete application bundle with all modules (uber-JAR)  |
+| **Infrastructure**                         |                |                                                          |
+| `openfasttrace-parent`                     | ❌              | Base parent POM (build infrastructure)                   |
+| `openfasttrace-mc-deployable-parent`       | ❌              | Deployment parent POM (build infrastructure)             |
+| `openfasttrace` (root)                     | ❌              | Root aggregator POM (build infrastructure)               |
+
+Legend:
+
+✅ Deployed to Maven Central: Public API modules that external users can depend on
+
+❌ Not Deployed: Internal infrastructure, test utilities, and build configuration
+
+### Why Two Parent POMs?
+
+As you can see in the table above, not all modules are intended to be deployed on Maven Central. The distinction is made by using two parent POMs. 
+
+The base POM is `openfasttrace-parent`, it mainly contains common dependencies and build configuration. On top of that, `openfasttrace-mc-deployable-parent` adds signing and Maven central deployment. 
+
+This structure ensures that only user-facing components are published to Maven Central while keeping internal development tools and build infrastructure private.
diff --git a/exporter/common/pom.xml b/exporter/common/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-exporter-common</artifactId>
     <name>OpenFastTrace Exporters Utils</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/exporter/specobject/pom.xml b/exporter/specobject/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-exporter-specobject</artifactId>
     <name>OpenFastTrace Specobject Exporter</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/lightweightmarkup/pom.xml b/importer/lightweightmarkup/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-lightweightmarkup</artifactId>
     <name>OpenFastTrace Lightweight Markup Importer Base</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/markdown/pom.xml b/importer/markdown/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-markdown</artifactId>
     <name>OpenFastTrace Markdown Importer</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/restructuredtext/pom.xml b/importer/restructuredtext/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-restructuredtext</artifactId>
     <name>OpenFastTrace reStructuredText Importer</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/specobject/pom.xml b/importer/specobject/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-specobject</artifactId>
     <name>OpenFastTrace Specobject Importer</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/tag/pom.xml b/importer/tag/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-tag</artifactId>
     <name>OpenFastTrace Tag Importer</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/xmlparser/pom.xml b/importer/xmlparser/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-xmlparser</artifactId>
     <name>OpenFastTrace Common XML Parser</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/importer/zip/pom.xml b/importer/zip/pom.xml
@@ -5,9 +5,9 @@
     <artifactId>openfasttrace-importer-zip</artifactId>
     <name>OpenFastTrace Zip Importer</name>
     <parent>
-        <relativePath>../../parent/pom.xml</relativePath>
+        <relativePath>../../openfasttrace-mc-deployable-parent/pom.xml</relativePath>
         <groupId>org.itsallcode.openfasttrace</groupId>
-        <artifactId>openfasttrace-parent</artifactId>
+        <artifactId>openfasttrace-mc-deployable-parent</artifactId>
         <version>${revision}</version>
     </parent>
     <properties>
diff --git a/openfasttrace-mc-deployable-parent/pom.xml b/openfasttrace-mc-deployable-parent/pom.xml
@@ -0,0 +1,85 @@
+<!--
+This parent POM specifically handles deployment configuration for modules that need to be published to Maven Central.
+
+It is maintained separately from the main parent POM for the following reasons:
+
+- Contains Maven Central specific configurations like GPG signing and deployment settings
+- Avoids cluttering the main parent POM with deployment-specific settings
+- Allows selective application of deployment configuration only to modules that need it
+- Provides flexibility to adapt deployment settings without affecting other modules
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>openfasttrace-mc-deployable-parent</artifactId>
+    <version>${revision}</version>
+    <name>OpenFastTrace Parent for modules deployed to Maven Central</name>
+    <packaging>pom</packaging>
+    <parent>
+        <relativePath>../parent/pom.xml</relativePath>
+        <groupId>org.itsallcode.openfasttrace</groupId>
+        <artifactId>openfasttrace-parent</artifactId>
+        <version>${revision}</version>
+    </parent>
+    <description>Free requirement tracking suite</description>
+    <url>https://github.com/itsallcode/openfasttrace</url>
+    <profiles>
+        <profile>
+            <id>central-publishing</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.sonatype.central</groupId>
+                        <artifactId>central-publishing-maven-plugin</artifactId>
+                        <version>0.7.0</version>
+                        <extensions>true</extensions>
+                        <configuration>
+                            <publishingServerId>central</publishingServerId>
+                            <autoPublish>false</autoPublish>
+                            <waitUntil>validated</waitUntil>
+                            <deploymentName>Manual deployment of OpenFastTrace</deploymentName>
+                        </configuration>
+                    </plugin>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-gpg-plugin</artifactId>
+                        <version>3.2.7</version>
+                        <executions>
+                            <execution>
+                                <id>sign-artifacts</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>sign</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                    <!-- This plugin needs to be skipped when using the central-publishing-maven-plugin
+ -->
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-deploy-plugin</artifactId>
+                        <version>3.1.4</version>
+                        <configuration>
+                            <skip>true</skip>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+    <distributionManagement>
+        <repository>
+            <id>central</id>
+            <name>Maven Central</name>
+            <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
+        </repository>
+        <snapshotRepository>
+            <id>central</id>
+            <name>Maven Central Snapshots</name>
+            <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
+        </snapshotRepository>
+    </distributionManagement>
+</project>
diff --git a/parent/pom.xml b/parent/pom.xml
diff --git a/product/pom.xml b/product/pom.xml
diff --git a/reporter/aspec/pom.xml b/reporter/aspec/pom.xml
diff --git a/reporter/html/pom.xml b/reporter/html/pom.xml
diff --git a/reporter/plaintext/pom.xml b/reporter/plaintext/pom.xml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# OpenFastTrace 4.2.0, released 2025-06-13`
	`1`	`+# OpenFastTrace 4.2.0, released 2025-06-14`
`2`	`2`
`3`	`3`	`Code name: Markdown code blocks`
`4`	`4`