cui-java-module-template

Status

Generated Documentation on github-pages

What is it?

This is a template repository for creating java-modules for cui-open-source-projects. This incorporates all necessary java-structures, including pom.xml, sensible project-documentation, an predefined github pipelines.

It is meant to be used as copy-paste-template.

Maven Coordinates

    <dependency>
        <groupId>de.cuioss</groupId>
        <artifactId>cui-java-module-template</artifactId>
    </dependency>

Customization

Automated Customization

This template provides an automated customization process to easily update all relevant project files:

1. Configure your project properties in customization.properties

2. Run the customization script: ./customize.sh

The script will update all required files with your project-specific information.

After running the script, you can review the changes in your git repository. The script will not commit or push any changes automatically, allowing you to verify them first.

After reviewing the changes, you delete the files customization.properties and ./customize.sh you can commit them to your repository.

Names / Keys

Create a new Repository by clicking "Use this template" If not using the automated customization process, manually replace all occurrences of cui-java-module-template with the new project 'key' / name, e.g. my-java-module. Relevant Files are:

Caution

The key must not contain spaces. They are used for creating urls as well.

• README.adoc → the badges on top

• pom.xml

• .github/project.yml → name, description, sonar.project-key, pages.reference only

• CLAUDE.md, .claude/skills/release/SKILL.md → the repository slug

• src/site/site.xml

• src/site/asciidoc/about.adoc

Warning

Do not touch release.current-version in .github/project.yml, and do not replace cuioss/cui-java-module-template in .github/workflows/release.yml (it only excludes this template from releasing). See Releasing.

Credentials

All secrets (GPG, Sonatype, Sonar, Release App) are managed at the cuioss organization level. The caller workflows pass them explicitly to the reusable workflows; pass only the secrets a reusable workflow declares, an undeclared one makes every run end in startup_failure. No repo-level secrets need to be configured.

After creating the repository

• cuioss-organization: add the repository to consumers: in .github/project.yml, so every org workflow release opens the pin-bump PR here. Apply repository settings and branch protection (merge queue) with the org’s repo-settings and branch-protection scripts.

• SonarCloud: create the project cuioss_<key>. New projects start with a main branch called master; rename it to main (Administration → Branches and Pull Requests) before the first analysis. Otherwise main is analysed as a short-lived branch and the overview stays empty. If it already happened: delete the short-lived main, then rename master. Set New Code to "Previous version". The first analysis of the renamed branch reports quality gate NONE (no baseline yet), which fails sonar.qualitygate.wait; the next analysis is green.

• Release: leave release.current-version alone, see Releasing.

Further Steps

• Verify that the customization was applied correctly to all files

• If you’re using manual customization:

  • pom.xml: Adjust name and description elements

  • Adjust module-info accordingly

  • pom.xml: Adjust property maven.jar.plugin.automatic.module.name according to your module-info

• src/site/asciidoc/about.adoc: Adjust content

• Review / Enable the elements under 'Security' Tab

• Review / Add Collaborators

• Add (link) the resulting maven-documentation: github.io-documentation

Customization Properties

The customization.properties file controls how the project is customized:

# Used in pom.xml (artifactId), README.adoc (badges), .github/project.yml (name, pages-reference) src/site/site.xml (links), SECURITY.md (links)
project.key=cui-java-module-template

# Used in pom.xml (<n> tag)
project.name=cui java module template

# Used in pom.xml (<description> tag)
project.description=Template module for cuioss open source projects.

# Used in pom.xml (property maven.jar.plugin.automatic.module.name)
project.moduleName=de.cuioss.template

# Used in pom.xml (groupId, README.adoc (badges))
project.groupId=de.cuioss

The script automatically derives additional properties: * project.scm.url - SCM URL based on the project key * project.pages.url - GitHub Pages URL based on the project key * project.sonar.id - Sonar ID based on the project key

Releasing

Merging a change of release.current-version in .github/project.yml is a release: the central guard in reusable-maven-release.yml publishes to Maven Central whenever that value differs from the merge commit’s first parent and no tag for it exists. Maven Central releases cannot be withdrawn. Every other project.yml edit reaches the release workflow too and is refused by the guard.

• This template declares current-version: 0.1.0 together with 0.1.0-SNAPSHOT in pom.xml, so a new repository never has to touch the value. Its first release is a deliberate workflow_dispatch from main.

• Every later release goes through the runbook .claude/skills/release/SKILL.md: a dedicated chore/release_<version> PR that changes nothing but the version, merged only after the pre-cut checks.

• The release workflow excludes this template repository itself, so it never publishes cui-java-module-template.