Nort Concepts

Internal

• Nova Ordis Release Tools User Manual

Overview

nort (Nova Ordis Release Tools) is a tool implementing logic that enforces a specific way of performing software releases. In this respect, it is opinionated. It enforces its opinions by driving various resources and tools (Maven, GitHub, artifact repositories, target systems upon the publicly-consumable artifacts are deployed, etc.) to interact in specific ways. nort is driven by a very simple set of top-level commands: "release", "build", "install" and "deploy", which trigger sequence of operations described below. Those sequences of operations involve relatively complex - and distributed - interactions. In most cases, you will only need to use "release". This article describes concepts that are useful if you want to understand how nort works.

Dot Version

A dot version is a label that marks a specific point in time in the evolution of a software project. It contains major, minor and patch components: "1.2.3". It does not contain a "SNAPSHOT" fragment. A dot version associated with an artifact indicates that the artifact was built based on source code that passed all the tests and it is ready for public consumption. The copy of the source tree of a project under active development in a work area is never associated with a dot version, as the project is "open for changes". For more details about this convention, see "Current Version" section.

Snapshot Version

A snapshot version is a label that marks a specific point in time in the evolution of a software project, and it primarily indicates that, at that time, the functionality provided by the project is not ready for public consumption. In other words, it says that source code tree used to build the artifact from was under development at the time the build was performed. The "SNAPSHOT" level designates a snapshot version. Example: "1.2.3-SNAPSHOT-5".

A snapshot-versioned artifact should never be used outside the development process. Snapshot-versioned artifacts may be routinely released, but they must only be used when dependent projects under development, themselves labeled with a snapshot version, require new functionality or defect fixes from their dependencies. In that situation, the dependency releases a snapshot release, the dependent updates its metadata to point to the newly released dependency snapshot release, and its development continues. When the dependent is ready for a dot release, first the dependencies are "dot released" and then the dependent is "dot released". nort provides logic to do the underlying bookkeeping and automate these workflows.

Current Version

The current version is the version designating the code base in the work area of a project. For Maven-built projects, it is the <version> information written into the POM file present in the work area.

Under the conventions enforced by nort, the current version is always a snapshot version, as projects are continuously evolving and they are in principle open for new functionality and defect fixes.

A version becomes a dot version during the release process. However, a dot version never lasts in a work area for more than a brief time interval. The dot version is used to build the corresponding artifacts (sources and binaries), which are then installed in their corresponding repositories, as part of the release process, and possibly even deployed "in production" - in places where they are used. If all goes well, the current version is immediately upgraded to the next logical SNAPSHOT. If something goes wrong, the current version remains set to the SNAPSHOT that failed to become a dot version, until the developer fixes the problem and repeats, successfully, the release process.

Release

A release consists in a sequence of operations - interactions with the local project work area, the build system metadata, and various external source code and binary repositories - which end with the generation of a set of release artifacts. Depending of the release type and the options used when the release was triggered, the set of released artifacts are different, and end up in different places. For more details, see the "sequences" section.

Release Types

Custom

For syntax details see the release command.

Sequences

The Release Sequence

The "release" sequence is potentially the most complex. The full release sequence involves release qualification (testing), project metadata updates, a build sequence, an install sequence and a deploy sequence. The user can instruct nort to end the process at a certain intermediate point, or start it from an intermediate point. For example, an already installed artifact can be deployed in production by triggering a deploy sequence.

The Qualification Sequence

During the qualification sequence, nort performs any metadata changes required by the version being released and insures the code base is ready for release.

The qualification sequence consists in the following steps:

1. Make sure the current version is a snapshot version.
2. If the release we're building corresponds to a dot version, increment the project version metadata, so we can perform the qualification with the correct version.
3. Execute all tests.
4. If the tests pass, pass the control to the next sequence, if any.
5. If the tests fail,

The Build Sequence

The build sequence insures that the project artifacts corresponding to the version being released are built, and placed in a conventional staging section of the work area. For Maven-built projects, that is the ./target directory.

The build sequence is usually triggered as part of the release sequence. It can also be initiated on its own. TODO: more details here.

The Install Sequence

The install sequence takes the artifacts built by the build sequence and installs them in their appropriate repositories. The terminology comes from Maven "install" and means installing artifacts into the local repository. In most cases, nort will indeed install the artifacts into the local Maven repository, but other options are also available.

The install sequence is usually triggered as part of the release sequence, following the build sequence. It can also be initiated on its own. TODO: more details here.

The Deploy Sequence

The deploy sequence takes the corresponding artifacts from the artifact repository and deploys them wherever they are supposed to be used. As an example, a command line utility can be deployed on a local system under the /usr/local directory, or in an Amazon EC2 environment. A web application packaged as an EAR can be deployed on the production web site, and so on.

The Release Sequence

Keep in mind that for a snapshot release, the snapshot version is already in the workarea. For a dot release, it is not, so the sequence is a bit different.

The release sequence consists in the following steps:

1. The release logic insures that the current version is a snapshot version. The release fails if it encounters a dot version in the work area.
2. Release qualification: test, what else?
3. All tests are executed.
4. If at least one test fails, NORT reports and fails. The work area is guaranteed to be left in the exact state it was found before the release sequence was initiated.
5. If release qualification passes, start the build sequence.
6. If the build sequence passes, start the installation sequence
7. If all tests pass, the artifacts corresponding to the release are built and placed in a staging directory in the work area (usually the target directory). If the artifact building fails, NORT reports and fails. The work area is guaranteed to be left in the exact state it was found before the release sequence was initiated.
8. Installed in the corresponding artifact repositories. Usually, JARs are installed under their corresponding artifact directories and binary releases are installed under their corresponding "release" modules, both in the local Maven repository. For more details about artifacts and what repositories are they installed into, see "Release Artifacts" section.
9. The installation sequence is automatically initiated, unless "release" command was configured to stop after execution.
10. The local workarea version metadata is tentatively incremented according to the rules described in the "Release Types" section.

Release Artifacts

A release may produce several kinds of artifacts.

Binary Distributions

Binary distributions are usually ZIP file containing everything an application needs in order to be installed on a new system. The binary distribution include libraries, wrapper scripts, release notes, documentation and possibly other files.

The recommended technique to build complex binary distributions is to add a dedicated "release" module to the project and let the Maven assembly plug-in to handle the process. The details are described in the "Building a Maven Complex Release Artifact" article.

If a project has a binary distribution that is built as Maven assembly, nort will install it in the local Maven repository, under the "release" project module.

Binary distributions may be built using a mechanism other than Maven - simply zipping files is perfectly valid - but irrespective to how the artifact is built, the install sequence ends with "installing" them them in some form of binary repository.

New Project Initialization

The command that carries out a new project initialization is nort initialize.

TODO:

• Verify that the POM of the new project contains the definition of maven.build.timestamp.format and release_date, as required by "Nova Ordis Utilities Version Metadata Handling" instructions. If it does not, inject it.