🚢 Versioning

We use SemVer for versioning Transformer.

All user-facing changes are tracked in our 🕰 Changelog.

Only the most recent version is supported: bugs in older releases are unlikely to be fixed if they don’t exist in the most recent release.

For all available releases, see the releases page.

Release process

Since #28, a new release of Transformer is created for each merge in the master branch. Therefore, every pull request needs to update the following files:

pyproject.toml

→ Update the version field.

docs/Changelog.rst

→ Create a new section describing what changed in the new version.

docs/conf.py

→ Update the version and release fields.

Each step is described in more details in Manual process. We also provide a best-effort Assisted process to simplify the whole operation.

Assisted process

To reduce the number of things you have to manually change, you can run one of:

• make prepare-patch
• make prepare-minor
• make prepare-major

depending on whether the new release is a patch, minor, or major release (according to the SemVer model). This computes the new version number for you and tries to update the corresponding files.

Warning

make prepare-... overwrites your files using patch. We recommend that you commit your changes before running it, so that you can easily revert its effects if necessary. This is particularly important if your own changes affect one of the files mentioned in Release process (e.g. you already edited the changelog).

Note

The make prepare-... script may not always work. If some of the files listed in Release process have changed too much since it was updated, it will not be able to patch them properly. In that case, please proceed manually as described in Manual process.

Warning

Please remember to document your actual contributions in the changelog yourself! make prepare-... only creates the boilerplate (new section, date, links). It cannot explain your changes (yet 😉).

Manual process

Choose the new version

The identifier of the new release must follow the vX.Y.Z format (where X, Y, and Z are integers), but the actual values for X, Y and Z totally depend on what has changed since the previous release.

• When you make incompatible API changes, increment X and set Y and Z to 0.
• Otherwise, when you add functionality in a backwards-compatible manner, increment Y and set Z to 0.
• Otherwise, when you make backwards-compatible bug fixes, increment Z.

In doubt, please refer to SemVer, which is the source of these guidelines.

Update pyproject.toml

In pyproject.toml, update the version value to X.Y.Z.

  [tool.poetry]
  name = "har-transformer"
- version = "A.B.C"
+ version = "X.Y.Z"

Update the Sphinx config

In docs/conf.py, update the version and release fields:

  # The short X.Y version
- version = "A.B"
+ version = "X.Y"
  # The full version, including alpha/beta/rc tags
- release = "A.B.C"
+ release = "X.Y.Z"

Update the changelog

Releasing a new version requires updating the 🕰 Changelog file to tell users what has changed since the last version in clear, concise and accessible terms. The git history is often not suited for this.

Assuming the current stable version is vA.B.C and new version is vX.Y.Z, you need to add a new “vX.Y.Z” section at the top of the file, just after the introduction. This new section should mention a release date and a GitHub link to observe the actual code changes since the last release.

This is summarized by this patch:

+.. _vX.Y.Z:
+
+vX.Y.Z
+======
+
+- Release date: YYYY-MM-DD HH:MM
+- Diff__.
+
+__ https://github.com/zalando-incubator/transformer/compare/vA.B.C...vX.Y.Z
+
 .. _vA.B.C:

 vA.B.C
 ======

Don’t forget to update the release date!