Versions

Code evolves over time, and versions provide a method for capturing a project's state at a given time stamp.

Orbit uses the semantic versioning scheme for capturing project's state at given time periods. Semantic versioning uses 3 numeric values to signify different levels of change.

version ::= major "." minor "." micro [ "-" label ]

To learn more about semantic versioning, visit the official website.

Determining the next version number based on a project's recent code changes can be an opinionated process, so it's recommended to also keep a changelog highlighting the differences among versions.

Note: An alternative to semantic versioning is calender versioning, which also operates on the basis of using 3 digits. To learn more about calender versioning visit the official website.

Rules

• Each level may only contain ASCII digits (0-9).
• A label must follow a dash character (-) and cannot be empty.
• Labels can consist of ASCII letters (a-z, A-Z), ASCII digits (0-9), and/or decimal characters (.)

All 3 levels must be given a numeric value consisting of only digits separated by a dot (.) character. This is considered a fully qualified version.

1.0.0

In some scenarios a partially qualified version can be accepted. This means one or more of the version's levels are omitted. A label is not required for a version to be considered fully qualified.

1
1.0

When given a partially qualified version, Orbit references the maximum version available that satifies the partially qualified version. If no version is specified, it assumes the request is for the latest known version. The latest known version can also be explicitly requested by inputting latest as the version. Assume the known released versions for a given IP are as listed:

The following illustrates the mapping from the partially specified requested version to its fully specified known version that would be returned:

Example

A fully qualified version must be written in every project's manifest file.

[ip]
# ...
version = "1.5.4"
# ...

A specific (or partially speific) version can be requested for an IP on the command-line by placing a colon : character between the package's name and the requested version.

$ orbit install gates:1.5.4
$ orbit get nor_gate --ip gates:1.5

Comparing versions

The following pseudocode provides additional help in learning about how versions are compared (selecting a "higher" version).

IF major levels are not equal:
    RETURN version with larger major level value.
ELSE IF minor levels are not equal:
    RETURN version with larger minor level value.
ELSE:
    RETURN version with larger patch level value.