Project

General

Profile

THIS IS AN INCOMPLETE DRAFT

Reason for this document

The art team has long used an informal set of rules to decide upon the numbering of releases. In order to better handle the relationships between the parts of the art suite, and in order for our experiments to better plan how and when they upgrade to newer releases of art, more formality is needed. This document proposes the means of doing so.

Experiments have several reasonable concerns when considering an upgrade to the version of the art suite upon which they build their code.
1. Will there be changes in behavior as a result of this change? Such changes can be changes in physics output, or changes in execution of workflows. Such changes can come from a change in the behavior of the art stack itself, or from a change in an underlying product (e.g. ROOT or Boost).
2. Will there be performance changes as a result of this change?
3. Will changes in source code be necessary?
4. Will files written by the new version be readable with the old version? (Note that we always make sure that files written by the old code can be read by the new code).

Users of the art suite do not typically care at which level a change of one of the types listed above is introduced; they care only about whether or not a change is present in a new release of the suite. Additionally, users of the art suite often notice only what the new version of the art suite is, and they do not often pay attention to the version numbers of the individual component packages.

Considerations

Reservation of names

In order to allow modifications internal to the art suite to avoid collision with experiment code, all names in the namespaces of the art suite are reserved to use by art. This means that no experiment code should be put into any of these namespaces. The facilities in the art suite that are intended to be customization points for experiment code are all written in a fashion that allows experiments to extend the functionality by writing code in their own namespaces, and not in one of the art suite namespaces.

Additionally, any code in the a namespace detail nested within one of the art suite namespaces should not be used directly by experiments, Such code is not part of the art suite's public API, and may be changed on any release.

The art suite namespaces include: art, mf, fhiclcpp, and cetlib.

Versioning specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).

Why not just use "Semantic Versioning" from http://semver.org ?

A popular description of another form of semantic versioning is found at http://semver.org. It is not suitable for our use because it requires a change in the MAJOR version whenever an incompatible API change is made. This is too different from what we have done historically.