Release Versioning#

The release versioning section describes the workflow and tools used in release versioning used as a Tudat Developer.

Learning Objectives

  1. Understand that “dependency hell” exists and how to avoid it.

  2. Understand MAJOR.MINOR.PATCH and when each of them are bumped.

  3. Understand the order of precedence for version labels.

  4. Obtain an overview of the Rever activities relevant to a Tudat developer.

  5. Understand what happens when rever <new_version_number> is executed.

  6. Be comfortable with the News Workflow for automated changelogs.

Semantic Versioning#

Tom Preston-Werner originally proposed a simple set of rules and requirements that provide a convention for modifying the versioning of software packages [4]. The opening paragraph introduces the concept of dependency hell:

In the world of software management there exists a dreaded place called “dependency hell.” The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair.

This chapter relays the Semantic Versioning (SemVer) 2.0.0 convention in an effort to avoid any developer needed “dependency hell” to be defined. It is further mentioned that the proposed system will only work with an API declaration:

For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number.

The SemVer 2.0.0 can be summarised by the following set of rules: Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards compatible manner, and

  • PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. SemVer only focuses on API compatibility, however there are common labels appended to the semantic version, for example 1.0.0-alpha. The list of requirements for the label formatting are detailed in SemVer. The important takeaway is that precedence is alphanumeric:

Precedence: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta
          < 1.0.0-beta  < 1.0.0-beta.2  < 1.0.0-beta.11
          < 1.0.0-rc.1  < 1.0.0.

Example

A proposed guided example flow is as follows:

  • alpha = in development without caring about (old) unit-tests

  • beta = in development and the old (unit) tests are valid

  • rc.1 = tests for new features are written and valid

  • rc.2 = additional tests had to be written and those were made valid

  • rc.3 = more additional tests that were made valid

However this is just an example flow, not a further set of rules. Depart from it whenever it improves your content.

Break any of these rules sooner than say anything outright barbarous.

—George Orwell, “Politics and the English Language”

Rever: Releaser of Versions!#

Installation

Using conda:

conda install rever -c conda-forge

Using pip:

pip install re-ver

Rever is a xonsh-powered (a language hybrid between bash script and Python), cross-platform software release tool. It automates standard activities that are carried out during a new release. It is important to be aware of these activities, as they are not only relevant at the moment of release. The tasks relevant as a Tudat Developer are:

  • authors

  • version_bump

  • changelog

  • tag

  • push_tag

  • bibtex

These tasks will be elaborated upon, one-by-one in the following subsections. Note that Rever will most likely be set up in repositories that you encounter, therefore the explicit procedure of Initializing Rever will not be covered here, though the relevant content is covered.

Example

Inside the developer-primer [2] repository used in Code Collaboration, you will find files that are used to configure Rever and some that are autogenerated or updated when executing a release.

 1 developer-primer
 2 ├── .authors
 3 │   ├── AUTHORS
 4 │   ├── .authors.yml
 5 │   └── .mailmap
 6 ├── bibtex.bib
 7 ├── CHANGELOG.rst
 8 ├── docs
 9 │   ├── build
10 │   ├── make.bat
11 │   ├── Makefile
12 │   └── source
13 ├── environment.yaml
14 ├── .gitignore
15 ├── LICENSE
16 ├── news
17 │   └── TEMPLATE.rst
18 ├── README.rst
19 ├── rever.xsh
20 └── source
21     └── tree_trunk.txt

The highlighted lines indicate the relevant components of the repository which relate to Rever configuration and activities. Grouped by their activity:

Activity

Components

authors

  • .authors/*

bibtex

  • bibtex.bib

changelog

  • news/*

  • CHANGELOG.rst

Finally, the rever.xsh is the configuration file for Rever.

rever.xsh#

The starting point for setting up or maintaining releases versioning with Rever is the configuration file rever.xsh. As noted in the introduction, Rever uses xonsh, which is a language hybrid between bash script and Python. There’s a good chance that if you know either of these, or both, you will feel right at home. The following rever.xsh file is a slimmed down version of the rever package’s release configuration.

basic rever.xsh#
$PROJECT = 'rever'
$ACTIVITIES = [
              'version_bump',  # Changes the version number in various source files (setup.py, __init__.py, etc)
              'changelog',  # Uses files in the news folder to create a changelog for release
              'tag',  # Creates a tag for the new version number
              'push_tag',  # Pushes the tag up to the $TAG_REMOTE
              'pypi',  # Sends the package to pypi
              'conda_forge',  # Creates a PR into your package's feedstock
              'ghrelease'  # Creates a Github release entry for the new tag
               ]

$CHANGELOG_FILENAME = 'CHANGELOG.rst'  # Filename for the changelog
$CHANGELOG_TEMPLATE = 'TEMPLATE.rst'  # Filename for the news template

This configuration demonstrates a basic setup for Rever. The variables $PROJECT and $ACTIVITIES are mandatory. Some activities may fail without further variable declarations. The following sections will elaborate sufficiently on some of the variables relevant to a Tudat Developer’s workflow.

Note

Rever has a well maintained, easy to read, explanation on all the options available for each activity in their activities documentation.

Example

Inside the developer-primer [2] repository, the following configuration is used:

developer-primer/rever.xsh#
 1$PROJECT = 'developer-primer'
 2$ACTIVITIES = [
 3    'version_bump',
 4    'authors',
 5    'changelog',
 6    'tag',
 7    'push_tag',
 8    'bibtex'
 9]
10
11# VersionBump related ------------------------------------------------------- #
12$VERSION_BUMP_PATTERNS = [
13    ('README.rst', r'\sVersion:\*\*\s.*', '\sVersion:** $VERSION'),
14    ('docs/source/conf.py', r'release\s=\s.*', "release = '$VERSION'"),
15    ('docs/source/index.rst', r'\sVersion:\*\*\s.*', '\sVersion:** $VERSION'),
16]
17
18# Authors related ----------------------------------------------------------- #
19$AUTHORS_DIR = ".authors"  # this is custom
20$AUTHORS_FILENAME = $AUTHORS_DIR + '/' + 'AUTHORS'
21$AUTHORS_TEMPLATE = '\n{authors}\n'
22$AUTHORS_METADATA = $AUTHORS_DIR + '/' + '.authors.yml'
23$AUTHORS_MAILMAP = $AUTHORS_DIR + '/' + '.mailmap'
24
25# Changelog related --------------------------------------------------------- #
26$CHANGELOG_FILENAME = 'CHANGELOG.rst'  # Filename for the changelog
27$CHANGELOG_TEMPLATE = 'TEMPLATE.rst'  # Filename for the news template
28
29# BibTex related ------------------------------------------------------------ #
30$BIBTEX_AUTHORS = 'G.H. Garrett'
31$BIBTEX_URL = 'https://github.com/tudat-team/developer-primer'
32
33
34
35# PushTag related ----------------------------------------------------------- #
36$PUSH_TAG_REMOTE = 'git@github.com:tudat-team/developer-primer.git'

version_bump#

The version_bump activity will uses an environment argument $VERSION_BUMP_PATTERNS which is of the form List[tuple[str, str, str]]. These tuples defined a file path, a regular expression (regex) pattern, and a replacement string. The regex match(es) in the specified file will be replaced by the desired string.

$VERSION_BUMP_PATTERNS = [
    ("file_path", r"regex_pattern", "replace_with"),
    ...
]

The use of regex is minimal and in most cases you can use examples in existing repositories.

Tip

A very polished resource for testing regex, even allowing for the export of code in your preferred language is regular expressions 101.

Example

Inside the developer-primer [2] repository used in Code Collaboration, you will find files that are used to configure Rever and some that are autogenerated or updated when executing a release.

developer-primer/rever.xsh#
12$VERSION_BUMP_PATTERNS = [
13    ('README.rst', r'\sVersion:\*\*\s.*', '\sVersion:** $VERSION'),
14    ('docs/source/conf.py', r'release\s=\s.*', "release = '$VERSION'"),
15    ('docs/source/index.rst', r'\sVersion:\*\*\s.*', '\sVersion:** $VERSION'),
16]

Todo

@team, does this need further elaboration?

authors#

Manages keeping a contributors listing up-to-date. Executing rever <version> will ensure all contributors to the repository are added to the AUTHORS file. By default, this is ordered by number of commits. This activity will also track all contributors since the last release, tracking all authors who contributed to the following release. These are taken directly from git logs, and mapped to an author through the .authors.yaml file. When setting Rever up, or committing to a repository for the first time, you may need to manually edit the .authors.yaml file. For example, if you have committed using multiple identities, but with the same email, you will need to set your main identity, with all others listed as aliases in the .authors.yaml file.

Todo

Example admonition adding oneself to the author configuration of .authors.yaml.

changelog#

Todo

changelog subsection.

tag#

Todo

tag subsection.

push_tag#

Todo

push_tag subsection.

bibtex#

Todo

bibtex subsection.

Rever commands#

Command

Description

rever setup

Generates activity support files.

rever check

Check activities.

rever <new_version_number>

Executes all activities for release.

News Workflow#

One of the most helpful features of rever is the changelog activity. This activity produces a changelog by colating news files. The changelog is written into the repo and can be used in the GitHub release activity.

Important

Ensure that you have one commit prior to executing rever <MAJOR.MINOR.PATCH>, otherwise you will not appear as an author on the Change Log.

  1. Go into the news/ directory

  2. Copy the TEMPLATE.rst file to another file in the news/ directory. We suggest using the branchname:

$ cp TEMPLATE.rst branch.rst

  1. The news files are customizable in the rever.xsh files. However, the default template looks like:

**Added:**

* <news item>

**Changed:**

* <news item>

**Deprecated:**

* <news item>

**Removed:**

* <news item>

**Fixed:**

* <news item>

**Security:**

* <news item>

  1. In this case you can remove the * <news item> and replace it with your own news entries, e.g.:

**Added:**

* New news template tutorial

**Changed:**

* <news item>

**Deprecated:**

* <news item>

**Removed:**

* <news item>

**Fixed:**

* <news item>

**Security:**

* <news item>

  1. Commit your branch.rst.

Feel free to update this file whenever you want! Please don’t use someone else’s file name. All of the files in this news/ directory will be merged automatically at release time. The <news item> entries will be automatically filtered out too!

Once the project is ready for a release when running the rever command all the files, except the template, in the news folder will be collated and merged into a single changelog file.

Todo

Example admonition adding a topic of interest to developer-primer/docs/interests.yaml, then following the news workflow to inform other developers. This is then concluded with the developer executing their first release.