Nort User Manual

Internal

• nort

Concepts

Concepts

Global Options

-v|--verbose

Enable verbose execution

-d|--debug

Starts the JVM in debug mode.

release

The command queries or modifies release information metadata for the current workarea and performs the sequence of steps required to do a full (by default) or partial release. For more details about what a release is, and what those steps are, see the "Release" section.

To query the work area and display the current version, execute:

release info

To initiate a release sequence, use:

release major|minor|patch|snapshot|<custom-release-string>

For more details on what a release sequence does, see the "Release Sequence" section.

If a custom release string is used, the string is checked for consistency. The release process will fail if the version string is invalid or represents an older version than the current.

release Command Options

--no-tests

Prohibits running the test suite suite during the qualification sequence. All other release sequence steps will be executed unchanged.

Not usually recommended, unless a snapshot is released.

--no-push

If this flag is used, there won't be any attempt to push any changes (artifacts or source code) to remote repositories during the publish sequence. The artifacts will be built and published in the local artifact repository. The code changes will be committed and tagged in the local source repository only.

This option is useful when the release process takes places off-line.

Clarify the situation when we want to push those artifacts later.

--no-install

Performs a full release sequence minus the install sequence.

This option is useful when we want to make the artifacts corresponding to the current version available to dependencies, but we don't necessarily want to overwrite the production-installed version. When --no-install is used, the artifacts are published as usual, and the completion sequence is executed. However, the qualification sequence does not perform any verifications related to the installation sequence.

build

The command creates releasable artifacts (binary distributions or libraries, depending on the nature of the project) for the current version. If the build process is successful, the artifacts are stored in the build area ("target" directory, for Maven) of the current work area.

nort initialize

Initializes a new project.

For more details on new project initialization see:

New Project Initialization

Convenience Wrappers

Tests

t [-c] [-d] <class-name>

-c: clean

-d: start in debug mode

Configuration

Configuration values support variable substitution. For an explanation of how variable substitution works see

Variables

The Qualification Section

The qualification configuration section is introduced by the "qualification:" top-level element:

qualification:
  ...

It contains the following configuration elements:

os.command.to.get.installed.version

qualification:
  os.command.to.get.installed.version: nort version

The Build Section

The build configuration section is introduced by the "build:" top-level element:

build:
  ...

The Publish Section

The publish configuration section is introduced by the "publish:" top-level element:

publish:
  ...

It contains the following configuration elements:

local.artifact.repository.root

publish:
  local.artifact.repository.root: ${M2}

release.tag

publish:
 ...
 release.tag: 
 ...

For more details on the publish sequence and the role the release tag is playing, see:

nort Concepts - The Publish Sequence

truststore

In case the publishing process needs to publish to a remote artifact repository that is protected by a self-signed certificate, the Java SSL layer will refuse to establish a SSL connection, unless we indicate that we trust the certificate. This is done by importing the remote server certificate into a local truststore, and configuring the Java SSL layer to use the truststore. The procedure to obtain the certificate and import it into a truststore is described here: Configure a Java HTTP Client to Accept Self-Signed Certificates.

If we need to configure nort to publish into a remote artifact repository protected with self-signed certificates, add a "truststore" map to the "publish" section, as follows:

publish:
  ...
  truststore:
    file: /Users/ovidiu/.m2/some-maven-repository.truststore
    password: ${TRUSTORE_PASSWORD}

If the file is specified with a relative path, it is considered to be relative to the configuration file parent directory.

The password can be specified in-line or as an environment variable. Since the Nort configuration file may be checked into a public repository, it is recommended to use environment variables and set the password in the local environment that does the build.

For more details about publishing to remote repository, see:

Publishing to Remote Artifact Repositories

The Install Section

The install configuration section is introduced by the "install:" top-level element:

install:
  ...

It contains the following configuration elements:

installation.directory

install:
  installation.directory: ${RUNTIME_DIR}

Usage

TODO: Coalesce https://github.com/NovaOrdis/novaordis-release-tools/blob/master/README.md with this content.

In-line help is available with:

operations

which is the original name of the script and it should be available in the ./bin subdirectory.

The latest output:

NOMBP2:events ovidiu$ operations
Nova Ordis Release Tools

Usage:

    <command> [global-options] <command-arguments> | operations [global-options] <command> <command-arguments>

Global Options:

    -v | --verbose - verbose execution.

Commands:

    install [-f|--force]

    release <snapshot|minor|major|patch|"version-string">

        Makes a release by incrementing the release information appropriately, running all tests, building the final
        artifact and installing the artifact in the appropriate repository. If a version string is used, the string
        is checked for consistency. The release process will fail if the version string is invalid or represents an
        older version than the current version.

     test - internal release tools testing shortcut. Advanced users only.

Installation:

    ./src/main/bash/operations install-release-tools <project-home-directory>

        The installation functionality can currently only be accessed from the original repository.
        'install-release-tools' installs the release tools into the 'bin' subdirectory of the specified project home
        directory. A target directory qualifies as "project home directory" if it has a Maven pom.xml in it. If an
        older version of the release tools is already installed, 'install-release-tools' will upgrade in place.

Per-Project Configuration:

    Create an operations.conf in the directory the release tools were installed into and configure local project
    properties.

Usage from the Project's README.md

TODO integrate:

1. 1. `install`

Bash script that exposes a unified command interface for installing the project's artifacts locally or remotely. Usage details are available with:

   ./install --help

   Provider of a uniform command set to build the installable artifact and install it locally or
   remotely.

       ./install [--verbose|-v] [--force] [--clean] [--no-tests] [--zip-only] [environment-name]

   Where:

       --force -   if the version being installed is already installed, the script will stop,  unless
           --force is specified.

       environment-name -   the name of the environment to install into.  If  not  specified  install
           locally.  A list  of  environments  and  associated  configuration  can  be  found  in the
           ./util/environments directory.

   Other Options:

       --help

       --clean - performs an maven clean before attempting to build

       --no-tests

       --zip-only - does not perform the last step of actually installing the zip, just builds it and
           leaves it in the ./target directory.

1. 1. run wrapper

The run wrapper contains the logic required to parse standard command line arguments such as --debug or --verbose, to build the classpath and to provide a command line entry point for the application. It is designed to work correctly even if the name chages from 'run' to whatever the application requires.

`install` script will identify the main class automatically and update `run` (or whatever the name of the wrapper script is) with it.

User Manual

Releases

A release consists in a tag in the repository plus a series of binary artifacts that are automatically uploaded into a binary repository. If the project produces a a Java library, that binary repository is usually a Maven repository. If the project produces an executable, the binary repository is GitHub's "release" facility. Running the "release" command consists, in order, of the following steps:

1. Increment the local version information (in the pom.xml file, for example).
2. run tests
3. produce the distributable binaries
4. tag the repository (TODO)
5. upload the distributable binaries into the binary repository (TODO)
6. increment the local version to reflect the next snapshot (working version) (TODO)