Lifecycle Model

Conceptual Model

As with software, knowledge artefacts follow a lifecycle with identified states, representable by a state diagram. A traversal through the state diagram corresponds to the development of changes to an artefact leading to a release of a specific version.

Although somewhat peripheral to the scope of artefact identification, we describe a 'de facto' lifecycle for three reasons:

to provide at least one lifecycle definition for users who have no other definition available;
to provide explicit terminology for states and transitions for use in this and other specifications;
to concretise the relationship between versioning and state transitions that commonly occur in software and other formal artefact development.

The lifecycle defined here is shown below.

Figure 1. Development Lifecycle

A multi-level model is used, where some states have 'micro-states', and top-level states are known as 'macro-states'. The intention is to provide standard names for all macro-states, while suggesting and allowing micro-states where they make sense. Macro-state names are the basis for software version identification - 'development' corresponds to the -alpha variant, 'release_candidate' to the -rc variant. Micro-states are useful to indicate because they define names for finer-grain states typically supported in artefact repositories.

This lifecycle assumes that artefacts start life either in an 'unmanaged' environment or directly in a managed one. In the latter case, it is assumed that there is some distinction between the developers' view and the 'release' view.

The key states are defined with names (dark blue) and transitions (light blue) that correspond to typical software and document development terms. Typical traversals through the lifecycle are:

[ unmanaged → ] development → published
development … development → release_candidate → … release_candidate ⇒ published
published → deprecated
development → rejected

A few linguistic conventions used here are worth noting:

start_review is the name of all actions entering the development macro-state;
release as an action (i.e. state transition) is taken to mean making any version of an artefact available to the public user base, including pre-releases, final releases and post-releases ('builds' in semver.org parlance);
publish as an action means to make a definitive release.

Lifecycle-based Versioning

The correspondence of versioned human-readable identifier and lifecycle states can now be described, according to the illustration below.

Figure 2. Development Lifecycle with Versioning

The version identifier evolves according to the general rules described above, and specific rules related to the lifecycle states, as follows.

An artefact normally starts life at 0.0.1, although it is acceptable practice to start at some other v0 version e.g. 0.5.0 to indicate approximately how mature the artefact is. It remains as a v0.x version for a period of unstable early development leading to an initial releasable 1.x version.
At some point, the artefact will be uploaded to a managed repository, at which point its identifier will be prepended with the management organisation namespace (and may change in other ways) and will have -alpha appended.
During initial 'v0' development, an artefact is considered to be unstable, i.e. any kind of changes may be made, reversed, redone and so on; due to this, the minor and patch version numbers are updated freely, and typically less often than the rules dictate for post-v0 development. is formed from the next version number that corresponds to the magnitude of the changes currently in the artefact, and appended with -alpha.
An artefact may be rejected, in which case the artefact lifecycle state is set to rejected (the version identifier is not changed).
At some point, the authoring team of an artefact will decide the artefact is ready for release. Its release version id is either v1.0.0, or else calculated as a function of the difference between the current form and the base version on which it is based.
It is then either:
- published into a pre-release cycle, at which point the numerical part of the version is computed according to the difference between the current form of the artefact and the release version on which it is based. The form of the identifer becomes M.N.P-rc.B, which indicates a community testing phase. From the release_candidate state, three paths are possible:
  - publish definitively with a stable version id of the form M.N.P;
  - release a newer release candidate, containing only changes that do not break the interface, i.e. patch-level changes or less; update the instance UID in any case;
  - if larger changes are needed, go back into the development state and perform larger changes as needed;
- released directly to a stable version of the form M.N.P.
An artefact may eventually be deprecated, in which case the artefact lifecycle state is set to 'deprecated' (the version identifier is unchanged). It may be classified inside the repository registry as obsolete, suspended or in some other way.

According to the basic version rules and the lifecycle model above, the 'precedence' of version identifiers follows is exemplified by the following:

    1.2.3-rc.1 < 1.2.3-rc.2 < 1.2.3 < 1.2.4-alpha < 1.3.0-alpha < ... < 1.3.0