Release Versioning§

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

Learning Objective(s)

  1. Understand what “dependency hell” is and how to avoid it.

2. Understand MAJOR.MINOR.PATCH and when each of them are bumped. 3. 3. Understand what happens when rever <new_version_number> is executed. 4. Understand how to maintain the automated changelog.

Semantic Versioning§

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. [3]

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.

Rever: Releaser of Versions!§

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.

Try it yourself!

Inside the Developer Primer 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
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
 developer-primer
 ├── AUTHORS
 ├── CHANGELOG.rst
 ├── docs
 │   ├── build
 │   ├── make.bat
 │   ├── Makefile
 │   └── source
 ├── environment.yaml
 ├── LICENSE
 ├── news
 │   └── TEMPLATE.rst
 ├── README.rst
 ├── rever.xsh
 └── source
     └── tree_trunk.txt

  • AUTHORS is a file listing the authors of the repository. The Developer Primer repository has the author activity set to default such that these names appear ordered according to an authors number of commits.

  • CHANGELOG.rst is a file, that is appended to automatically during the changelog activity. Developers do not modify this file directly, unless a mistake was made in the activity during release.

  • news is a directory for the changelog activity again. The TEMPLATE.rst is copied by a Developer and renamed to their name or the branch name as described in News Workflow.

  • rever.xsh configures Rever. Activities can be added and removed here, and default settings can be changed (e.g. filenames, author ordering).

Authors§

rever.xsh§

$PROJECT = 'tudat-developer-docs'
$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
               ]
$VERSION_BUMP_PATTERNS = [  # These note where/how to find the version numbers
                         ('docs/conf.py', r'release\s*=.*', "release='$VERSION'")
                         ]

$CHANGELOG_FILENAME = 'CHANGELOG.rst'  # Filename for the changelog
$CHANGELOG_TEMPLATE = 'TEMPLATE.rst'  # Filename for the news template
$PUSH_TAG_REMOTE = 'git@github.com:tudat-team/tudat-developer-docs.git'  # Repo to push tags to

$GITHUB_ORG = 'tudat-team'  # Github org for Github releases and conda-forge
$GITHUB_REPO = 'tudat-developer-docs'  # Github repo for Github releases  and conda-forge

Adding a new Author§

.authors.yml

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.