hmpps-digital-prison-reporting-mi-lib

Common library to create reports.

This project is generated from ministryofjustice/hmpps-template-kotlin

Requires Java 19 or above

CODEOWNER

• Team : hmpps-digital-prison-reporting
• Email : digitalprisonreporting@digital.justice.gov.uk

Overview

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.

Local Development

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

Testing

Note - test coverage reports are enabled by default and after running the tests the report will be written to build/reports/jacoco/test/html

First time set up

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.sock

Unit Tests

The unit tests use JUnit5 and Mockito where appropriate. Use the following to run the tests.

    ./gradlew clean test

Contributing

Please adhere to the following guidelines when making contributions to the project.

Documentation

• Keep all code commentary and documentation up to date

Branch Naming

• Use a JIRA ticket number where available
• Otherwise a short descriptive name is acceptable

Commit Messages

• Prefix any commit messages with the JIRA ticket number where available
• Otherwise, use the prefix NOJIRA

Pull Requests

• Reference or link any relevant JIRA tickets in the pull request notes
• At least one approval is required before a PR can be merged

Versioning

• Use semantic versioning to indicate the scope of the change.
• New versions can be published using the Publish GitHub action

Integrating to your Spring Boot project

See Integrating into your Spring Boot project.

Publishing Locally

Run the following command to publish the artifact to your local maven repository: ./gradlew publishToMavenLocal

Publishing to Maven Central

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.

Technical Details of Publishing to Maven Central

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.

Authenticating with Sonatype

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.

Handling Failed Publications

If the library fails to be published then it might have failed validation in the Sonatype Staging repository so check there for some clues.

Creating a Sonatype User

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.

Adding Credentials to a Publish Request

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.

Changing the Sonatype Credentials

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.

Signing a Publish Request to Maven Central

One of the requirements for publishing to Maven Central is that all publications are signed using PGP.

Signing a Publication on Circle CI

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.

Note: The current signing key has an expiration date of 16 October 2024 at 15:12.

Changing the Signing Key

• Generate a new key - follow the Sonatype guide.
• Export the private key to a file - google for gpg export private key and you should find several guides for using gpg --export-secret-keys.
• To allow the private key to be inserted into Circle, convert the newlines in the private key to \n see this forum if you have problems with this.
• Delete the environment variables ORG_GRADLE_PROJECT_signingKey and ORG_GRADLE_PROJECT_signingPassword from the Circle CI env vars page
• Recreate the environment variables where ORG_GRADLE_PROJECT_signingKey contains the private key (with newlines) and ORG_GRADLE_PROJECT_signingPassword contains the passphrase.

Data Product Definitions (DPDs)

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