POST-SNAPSHOT Versions

*-POST-SNAPSHOT versions are post-release builds that exist after a release and before a new *-SNAPSHOT is started. They are used to allow updating documentation (both Javadocs and published books) as well as ensuring that current releases still compile against newer dependencies and Java versions.

We use the post-release version as a placeholder, meaning nothing in the project has yet changed that will cause another release of the project. We then bump to the next *-SNAPSHOT only on an as-needed basis. This allows us to know the state of the project without any outside or complicated tracking: if it is *-POST-SNAPSHOT we're holding at the current version, and if it is *-SNAPSHOT the project is in the process of moving forward.

We find following the standard convention of bumping to the next *-SNAPSHOT version immediately after a release to be insufficient. It raises three issues:

1. Will the next release be a MAJOR, MINOR, or PATCH? This is usually not yet known so there is no clear answer.
2. Since the project would immediately be on the next *-SNAPSHOT version, does it have any changes that warrant a release?
3. Should this project be released before any dependent projects are released?

Changes within POST-SNAPSHOT versions must not change functionality and must not be significant enough to warrant a future release of the project. For example, post-release builds may contain the following changes without being promoted to the next *-SNAPSHOT version:

• Updated build process:
  • Updated parent POM
  • Updated POM
  • Updated Java version
  • Updated Maven plugin versions
  • Updated dependency versions
  • Updated unit tests
• Updated documentation:
  • Updated javadocs
  • Updated book/ sub-project
• Non-breaking, completely compatible code changes:
  • Deprecated methods and classes
  • Renamed private fields and local variables
  • Other changes to white-space or comments
  • Any other non-breaking, completely compatible code changes that alone do not warrant a new release

The moment a project has a change that is worthy of being released, it will be bumped to the next *-SNAPSHOT version, typically in a manner compatible with Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH).

Because both the Javadocs (apidocs) and related SemanticCMS book content may be updated without requiring a new release of a project, we always publish the current *-POST-SNAPSHOT or *-SNAPSHOT Javadocs and book.

All supported parent POM contain the "POST-SNAPSHOT" Maven profile. When activated, this profile defines a single property ${POST-SNAPSHOT} containing the value -POST-SNAPSHOT. When inactive, the ${POST-SNAPSHOT} property contains an empty string.

Property-based substitution is never used on releases, only on snapshot builds. So that releases only refer to other released versions, we comment-out as <!-- ${POST-SNAPSHOT} --> before the release, then restore after the release.

    <profile>
      <id>POST-SNAPSHOT</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <POST-SNAPSHOT>-POST-SNAPSHOT</POST-SNAPSHOT>
      </properties>
    </profile>

We strive to constantly move all supported projects forward as a unified set. All supported projects build against dependencies that are the current *-POST-SNAPSHOT or *-SNAPSHOT versions. However, the steps taken preceding a release depend on whether its dependency is a *-POST-SNAPSHOT or *-SNAPSHOT version.

If the dependency is a *-POST-SNAPSHOT, it is rolled-back to the specific version before the release and restored to *-POST-SNAPSHOT after the release. This is because post-release versions are never themselves released. If there were anything worthy of release, they would have already been bumped to the next *-SNAPSHOT version.

However, if the dependency is a *-SNAPSHOT, the dependency itself will typically be released before any of its dependent projects. Exceptions to this are rare, but possible. These exceptions usually require three conditions:

1. The dependency is not ready for release (which ideally it always would be).
2. The dependent project remains compatible with the previously released dependency version. This compatibility may be assumed when the dependency is only a PATCH version change. For MAJOR or MINOR versions, one must be more cautious.
3. The dependent project has some urgency and must be released before the dependency can be fixed/completed and released.

Post-release builds also allow NetBeans to correctly connect projects together for those who are actively developing multiple modules. By connecting projects, we are referring to NetBeans ability to recognize a dependency as being a local (and possibly currently opened) project. This allows proper cross-project behavior, such as showing latest javadocs and code-assist, opening the correct file in go-to-source, and properly operating in debug mode (line breakpoints, variables, …).

When using ${POST-SNAPSHOT} property-based dependency versions, this linking is only effective when the POST-SNAPSHOT profile is active.