Common library to create reports.
This project is generated from ministryofjustice/hmpps-template-kotlin
Requires Java 19 or above
This is a library which you can include into your project to create reports. It exposes three endpoints which are fully documented with OpenAPI documentation.
This project uses gradle which is bundled with the repository and also makes use of
- spring boot - as a web framework and for compile time dependency injection
- jacoco - for test coverage reports
Note - test coverage reports are enabled by default and after running the tests the report will be written to build/reports/jacoco/test/html
Before running tests for the first time, if you use Colima then you will need to run:
sudo rm /var/run/docker.sock
sudo ln -s $HOME/.colima/docker.sock /var/run/docker.sockThe unit tests use JUnit5 and Mockito where appropriate. Use the following to run the tests.
./gradlew clean test
Please adhere to the following guidelines when making contributions to the project.
- Keep all code commentary and documentation up to date
- Use a JIRA ticket number where available
- Otherwise a short descriptive name is acceptable
- Prefix any commit messages with the JIRA ticket number where available
- Otherwise, use the prefix
NOJIRA
- Reference or link any relevant JIRA tickets in the pull request notes
- At least one approval is required before a PR can be merged
- Use semantic versioning to indicate the scope of the change.
- New versions can be published using the Publish GitHub action
See Integrating into your Spring Boot project.
Run the following command to publish the artifact to your local maven repository:
./gradlew publishToMavenLocal
Publishing to Maven central takes place through the Circle CI build pipeline when there are changes to the main branch.
The pipeline has a step that requires manual approval to perform the publication.
This guide was used as a basis for publishing to Maven Central.
However, please note that the document above is old and a couple of things have changed.
- The Gradle plugin used in that document -
maven- is out of date and the maven-publish plugin is used instead. - The process described in the document above requires a manual step to release the library from the Nexus staging repository - we have implemented the Nexus Publish Plugin to automate this step.
When publishing to Maven Central we authenticate with a username and password.
The groupId (see Maven coordinates) of the project is uk.org.justice.service.hmpps.
We created a team user in Sonatype Jira and our team user was added to the group uk.org.justice.service.hmpps (see this Jira ticket that was raised).
This team user account that was created also gives us access to the Staging repository which is used to validate Maven publications before they are published.
If the library fails to be published then it might have failed validation in the Sonatype Staging repository so check there for some clues.
To get access to the Sonatype domain uk.org.justice.service.hmpps:
- Create a Sonatype user account
- Get an existing Sonatype user with access to the domain to raise a ticket requesting access for the new user account. See this Jira ticket as an example.
A valid Sonatype username and password are required to publish to Maven Central.
In build.gradle.kts we use environment variables OSSRH_USERNAME and OSSRH_PASSWORD to authenticate with Sonatype. These environment variables must be set when running the publish task.
Note that this means the environment variables have been set in Circle CI. This is safe as environment variables cannot be retrieved from Circle.
For account credentials management of Sonatype users this used to be performed through https://issues.sonatype.org/ . However, since 12/03/2024 this service has moved to https://account.oss.sonatype.org/realms/central-ossrh/account/.
If you need to change the secrets used to authorise with Sonatype delete the Circle CI environment variables (OSSRH_USERNAME and OSSRH_PASSWORD) and re-add them with the username and password of another Sonatype user with access to the domain.
One of the requirements for publishing to Maven Central is that all publications are signed using PGP.
In build.gradle.kts we use environment variables ORG_GRADLE_PROJECT_signingKey as recommended in the Gradle Signing Plugin documentation.
The current public signing key has been uploaded to this public keyserver as this is a sonatype requirement and it is using it to validate the signature.
- Generate a new key - follow the Sonatype guide.
- Export the private key to a file - google for
gpg export private keyand you should find several guides for usinggpg --export-secret-keys. - To allow the private key to be inserted into Circle, convert the newlines in the private key to
\nsee this forum if you have problems with this. - Delete the environment variables
ORG_GRADLE_PROJECT_signingKeyandORG_GRADLE_PROJECT_signingPasswordfrom the Circle CI env vars page - Recreate the environment variables where
ORG_GRADLE_PROJECT_signingKeycontains the private key (with newlines) andORG_GRADLE_PROJECT_signingPasswordcontains the passphrase.
The DPDs used by this library adhere to the DPD JSON schema hosted here: https://github.com/ministryofjustice/hmpps-digital-prison-reporting-data-product-definitions-schema/blob/main/schema/data-product-definition-schema.json