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