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

• SECURITY.adoc

• .github/project.yml

• src/site/site.xml

• src/site/asciidoc/about.adoc

Credentials

Add the necessary credentials to the project: "Settings" → "Secrets" → "Actions", as there are:

• GPG_PASSPHRASE → Code Signing

• GPG_PRIVATE_KEY → Code Signing

• OSS_SONATYPE_PASSWORD → Deploy to maven-central

• OSS_SONATYPE_USERNAME → Deploy to maven-central

• PAGES_DEPLOY_TOKEN → Deploying the result of maven site to https://cuioss.github.io

• SONAR_TOKEN → Sonar-Cloud

They are picked up in the predefined pipeline-configurations:

• .github/workflows/maven.yml

• .github/workflows/maven-release.yml

Ensure that the actions are authorized correctly: Settings > Actions > General > Workflow permissions > "Read and write permissions" must be selected not "Read repository contents permission"

Documentation on how to create a signing key can be found Documentation at cui-parent-pom

A sonar token can be derived from https://sonarcloud.io/account/security

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