Skip to content

Latest commit

 

History

History
136 lines (95 loc) · 5.6 KB

PUBLISHING.md

File metadata and controls

136 lines (95 loc) · 5.6 KB
Raw

Publishing

How to publish a new version of this library?

This library can be published to three different repositories:

  • GitHub Packages
  • Maven Central

Follow the setup to configure your system for manual publishing, and the repository for automatic publishing.

Publish Automatically

Automatic publishing is preferred over manual publishing. To publish a new version of the library automatically, follow the setup and then:

  1. Update the CHANGELOG.md with the latest changes: create a new release entry, and update the release links at the bottom of the file.
  2. Commit your changes and ensure there are no new or changed files in the repository.
  3. Use Git to create a tag with the new version number, such as 0.1.2-alpha. 
    git tag 0.1.2-alpha
  4. Verify that the version number is correctly picked up using: 
    ./gradlew printVersion
    The version number should not contain a commit hash and should not have the suffix .dirty.
  5. Push the tag to the remote repository: 
    git push origin 0.1.2-alpha
  6. Update the README.md and documentation to reflect the latest release of the library.

Publish Manually

To publish a new version of the library manually from the command-line, follow the setup and then:

  1. Build, sign, and publish the artifact, and then close and release the Maven Central repository using: 
    ./gradlew publish closeAndReleaseSonatypeStagingRepository
  2. Update the README.md and documentation to reflect the latest release of the library.

Close and Release the Staging Repository

The closeAndReleaseSonatypeStagingRepository task is used to close and release the Maven Central staging repository. If this is not done, the artifact must be released manually from Maven Central. To do so, follow these steps:

  1. Login into OSSRH.
  2. Go to 'Staging Repositories' on the left, click the 'Refresh' button at the top to see the repositories.
  3. Select the repository, and click the 'Close' button at the top. This will validate the package requirements. Wait for it to complete, by periodically clicking the 'Refresh' button at the top.
  4. Once successfully closed, click the 'Release' button to publish the package on Maven Central. The repository may be dropped after release. Again, wait for the operation to complete.
  5. Done! It can take a while for the new release to appear on Maven Central.

Setup

In your home directory at ~/gradle.properties, ensure the file contains properties for signing, publishing to Metaborg Artifacts, GitHub Packages, and Maven Central.

Signing

Obtain the short ID of the GPG subkey you want to use for signing. It's the 8-character part after the key's type:

gpg --list-secret-keys --keyid-format SHORT

Note: If you have a master key and multiple subkeys, use the key ID of the signing subkey ([s]).

The key's password you should already know, and the secret keyring file is not available by default in modern GPG versions. Export it using the following command, where $KEYID is the short key ID:

gpg --export-secret-keys $KEYID > ~/.gnupg/secring.gpg

Also export an ASCII-armored version of the secret key:

gpg --export-secret-keys --armor $KEYID

In the ~/.gradle/gradle.properties file in your home directory, add those values as the following properties (where <myusername> is your user account username):

# GPG Signing
signing.keyId=0ABA0F98
signing.password=WAWFAFDcKxNFgZ8YQnjHMrXuxn02
signing.secretKeyRingFile=/Users/<myusername>/.gnupg/secring.gpg

On the repository settings Secrets page, add those values as the following secrets:

  • SIGNING_KEY_ID: The short ID of the key, e.g., 0ABA0F98
  • SIGNING_KEY_PASSWORD: The password of the key, e.g., WAWFAFDcKxNFgZ8YQnjHMrXuxn02
  • SIGNING_KEY: the ASCII-armored key, starts with -----BEGIN PGP PRIVATE KEY BLOCK-----

GitHub Packages

For GitHub Packages, obtain the GitHub Personal Access Token (PAT) from the GitHub Developer Settings page. The token should have the read:packages and write:packages scopes. The username is your GitHub username.

In the ~/.gradle/gradle.properties file in your home directory, add those values as the following properties:

# GitHub Packages
gpr.user=MyUsername
gpr.key=ghp_BRW0dchXpF3QH5c5JJuGhXrgN9SHM1fMrVP4

No secrets need to be added to the repository settings Secrets page.

OSSRH Maven Central

The OSSRH username and token can be found as follows:

  1. Login into OSSRH.
  2. Click your username in the top-right, go to Profile.
  3. In the drop-down box, change from Summary to User Token.
  4. Click the Access User Token button. It will give a username and token.

In the ~/.gradle/gradle.properties file in your home directory, add those values as the following properties:

# OSSRH Maven Central
ossrh.user=bYpE4FzT
ossrh.token=T33RJJMfxWPlvKhA7pp9izcsgpwbA4FBY3hMoH3+bdk5

On the repository settings Secrets page, add those values as the following secrets:

  • OSSRH_USERNAME: The OSSRH token username, e.g., bYpE4FzT
  • OSSRH_TOKEN: The OSSRH token, e.g., T33RJJMfxWPlvKhA7pp9izcsgpwbA4FBY3hMoH3+bdk5