Skip to content

Creating SNAPSHOT versions

Jump to bottom
David Whitlock edited this page Jan 1, 2026 · 19 revisions

Starting in the Summer of 2021, I started using semantic versioning for the Maven artifacts for the course. Semantic versioning is required for Sonartype and deploying to Maven central. It's also the right thing to do.

But you can only upload a particular version of an artifact to Maven central once, so as I had to start using SNAPSHOT versions while I'm developing changes that will eventually go into a released version.

Because I've got so many artifacts in one GitHub repository and the tree of Maven projects is so big, the process for doing SNAPSHOT versions is a little tricky.

Here's what I've learned.

Replace all of occurrences of the current release version with the a SNAPSHOT version of the next version

Because of the project hierarchy and the fact that I often have to deploy all of the artifacts (especially when I want to make a change to the topmost pom.xml), it's easier just to update every artifact (and the first-party dependencies on the old version).

This is just a search-and-replace in IntelliJ.

Add a snapshot repository declaration to the top-level pom.xml

Add a <snapshotRepository> declaration at the end of the top-level pom.xml so that SNAPSHOT artifacts can be uploaded to the snapshot repository.

    <snapshotRepository>
      <id>ossrh</id>
      <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
    </snapshotRepository>

This declaration should be removed before release artifacts are published.

Deploy the snapshot artifacts without running tests

To get started quickly, I just deploy the SNAPSHOT artifacts (especially, the POMs) without running tests:

$ mvn -Darchetype.test.skip=true -DskipITs -DskipTests deploy

Enable Archetypes to use SNAPSHOT versions

Because SNAPSHOT artifacts are deployed to a different Maven repository, the following must be added to the first archetype project to be built so that the integration tests can download the dependencies of the projects instantiated from the archetype.

In projects-parent/archetypes-parent/student-archetype/src/main/resources/archetype-resources/pom.xml and projects-parent/archetypes-parent/java-koans-archetype/src/main/resources/archetype-resources/pom.xml

  <repositories>
    <repository>
      <name>Central Portal Snapshots</name>
      <id>central-portal-snapshots</id>
      <url>https://central.sonatype.com/repository/maven-snapshots/</url>
      <releases>
        <enabled>false</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

Deploy the SNAPSHOT builds of the java-koans project

Before the java-koans archetype will build (in GitHub CI), the SNAPSHOT version of the koans-lib must be deployed.

Wait for the deployed release artifacts to make it Maven Central

After the SNAPSHOT versions of the artifacts are satisfactory, the SNAPSHOT version should be replaced with the release version. Go ahead and deploy them.

Before you commit the release versions to GitHub, you'll need to wait for the artifacts to be mirrored in Maven Central:

https://repo.maven.apache.org/maven2/io/github/davidwhitlock/joy/joy/

Otherwise, the archetypes won't build on the Continuous Integration server and other machines (like the PSU machines) that don't have the release version of the artifacts in their local Maven cache/repository.

Promoting SNAPSHOT versions to released versions

There's a bit of a dance to deploy all of the dependencies in the right order.

  • In the JoyOfCoding repository, replace all text occurrences of the SNAPSHOT version (e.g. 1.2.3-SNAPSHOT) with the release version (e.g. 1.2.3)
    • This is the time to get rid of the <repository><snapshots> in pom.xml files. Be sure to perform a case-sensitive search and replace of -SNAPSHOT because -snapshot appears in the URL for the snapshot repository.
    • At one point, I thought we could revert the version changes in just the archetype projects. However, it looks like when a project hierarchy contains a mix of SNAPSHOT and non-SNAPSHOT versions, only the SNAPSHOT versions actually get deployed.
    • So, all of the versions need to deployed in one fell swoop. And you need to not run tests so that 1) it's fast and 2) the archetype project integration tests don't run (because they'll fail because the dependent artifacts aren't in Maven central yet)
    • $ mvn -Darchetype.test.skip=true -DskipITs -DskipTests clean deploy
  • After release artifacts have been deployed, they must be approved in order to be visible in Maven Central: https://central.sonatype.com/publishing/deployments. Refresh the page after a couple of minutes to make sure the status of the artifacts go from "Publishing" to "Published".
  • Wait for the released artifacts to be available in Maven Central:
  • Update the version of the java-koans artifacts, commit them to GitHub, and deploy them using mvn clean deploy
  • Commit the changes to the JoyOfCoding repository and push them to GitHub
    • Make sure that the CI build is successful
  • Update the versions of artifacts in the GettingStarted repository to reference the new version of the archetypes

Extend expiration date of signing keys every couple of years

If the jar signing step fails while running a mvn deploy, it might be due to the fact that the signing key has expired.

[INFO] Signer 'gpg' is signing 4 files with key default
gpg: no default secret key: No secret key
gpg: signing failed: No secret key

Follow the steps on https://central.sonatype.org/publish/requirements/gpg/#dealing-with-expired-keys to update the expiration date on the signing key.

Clone this wiki locally