Zenpack Versioning Guidelines

This guide covers ZenPack version and revision numbering.

Version Suffix

The version suffixes that have changed to better to conform to setuptools version parsing and PEP 440. Here’s how the auto-suffixing now works:

  1. Base version is read from setup.py’s VERSION. 1.2.3dev becomes 1.2.3 (just the release numbers are extracted)
  2. Suffix is automatically determined. See below.
  3. Suffix is added to base version.

How is suffix determined? It’s based on the branch type:

  • develop: .dev<commits>+g<ref>
  • release/*: rc<commits>+g<ref>
  • hotfix/*: rc<commits>+g<ref>
  • master: no suffix
  • support/*: .post<commits>
  • feature/*: .dev<commits>+g<ref>.<normalized-feature-name>

The <commits> is determined by running and extracting the second part of:

git describe --tags --always --long $BRANCH

The <ref> is determined by extracting the third part of the same command.

The <normalized-feature-name> is extracted from everything after feature/ in the branch name, and with all non alphanumeric characters converted to periods.

This should be completely compatible with the way we’re currently doing things, even if means that there’s some reordering to be aware of.

Another implication of this is that it’s no longer necessary to even put the “dev” suffix into setup.py’s VERSION.

The reason for these changes is to support the platform teams efforts in product-assembly which will be part of the new build system that assembles products from artifacts rather than attempting to build the whole monolith at once. There will be a manifest describing which version of each ZenPack to include in each product assembly. We want that manifest to be able to say things like:

ZenPacks.zenoss.PythonCollector>=1.8,<1.9

so we don’t have to remember to update multiple product manifests every time we make a patch to a ZenPack.

Version Numbering Guidelines

To get this kind of manifest expressiveness mentioned above, we need to make sure our versions order correctly. We also need to have discipline about when we’re fixing bugs vs. when we’re changing behavior.

The version format is:

<major>.<minor>.<patch>

The rules are:

  • Changing behavior in a non-backwards compatible way? Increment major.
  • Changing behavior in a backwards-compatible way? Increment minor.
  • Fixing a bug that doesn’t change behavior? Increment patch.

Note

The key points here are:

  • When working on ANY branch, you should set VERSION in setup.py to the next version you expect to be released from that branch without any suffix. Jenkins will handle the suffix.
  • So the same conventions we’ve been following all still apply. Bump the patch version when starting a hotfix branch. Bump the minor or major version after finishing a release branch.

References: