Software Versioning

Tsvetan Dimitrov

Agenda

  • Why versions?

  • Versioning Schemes

  • Release Management

  • CI Automation

  • Team Versioning Conventions

Why versions? / 1

  • keeps track of stable progress

  • aid QA process and bug reporting (confirm defective operation)

  • enable incremental patching

  • reverting to stable state

Why versions? / 2

  • multiple development flows

  • upgrade scheme for customer when offering new features

  • public version for customer (version code name)

  • private (internal version) - used in development

Versioning Schemes

Important Questions

Is it a bug or a feature?

Is it  backwards compatible or not?

Question 1
Question 2

Semantic Versioning / 1

  • Given a version number:

MAJOR.MINOR.PATCH-PRERELEASE+METADATA

  • MAJOR - incompatible API changes

  • MINOR - backwards-compatible new functionality

  • PATCH - backwards-compatible bug fixes

Semantic Versioning / 2

  • Given a version number:

MAJOR.MINOR.PATCH-PRERELEASE+METADATA

  • PRERELEASE 

    • For example: 3.1.0-beta, 1.2.0-rc, 4.1.3-preview, 2.3.0-alpha, 1.3.2-SNAPSHOT

    • Use SNAPSHOT during development phase and remove it before releasing

Semantic Versioning / 3

  • Given a version number:

MAJOR.MINOR.PATCH-PRERELEASE+METADATA

  • METADATA

    • further tagging of build label (usually a build number/timestamp/feature name/git commit)

    • does NOT participate in version ordering, i.e. versions that only differ in metadata are considered the same

Semantic Versioning / 4

  • Disadvantages

    • debatable if a behavior is a bug or feature

    • backwards incompatible bug fix -> MAJOR or PATCH?

    • semantic-release plugin solves this problem, but relies on extensive package coverage

Compatible Versioning / 1

Is it a bug or a feature?

Is it backwards compatible or not?

Question 1
Question 2

Compatible Versioning / 2

  • MAJOR.MINOR.0-PRERELEASE+METADATA

  • no PATCH versions

  • backwards compatible to SemVer

  • avoids personal judgement when assessing how to bump a version based on whether you have a feature or a bug

Release Management

  • Testing phase

  • Release phase

Testing phase

  1. Release builds on a nightly basis or manually.

  2. Targeted for testing on a staging. environment, e.g. 1.2.0-rc1.

  3. Could contain feature name as METADATA component, e.g. 1.2.0-rc1+feature_name.

  4. Introduce code freeze stage - only fix bugs, no new features (starts RC iterations).

  5. Promote tested versions to final version.

Release phase

  1. Tag final releases in git (includes build number).

  2. Set version in jar manifest (on build phase).

  3. Additionally tag docker images of final releases with the released version number.

  4. Generate release notes - JIRA built-in support

  5. Publish release notes on Github.

CI Automation

  • Setting versions (staging and prod jobs).

  • Tagging in Git.

  • Additionally tagging docker images with version tags.

  • Publishing release notes in Github.

  • Getting release notes from JIRA.

  • Dev jobs will be left unversioned (only build number docker tags).

Team versioning conventions / 1

  • How to name pre-releases, e.g. rc1, alpha, beta, preview...?

  • Should we use an autoincrement versioning mechanism?

  • Should and when shall we do code freeze?

  • Should we set sprint target versions?

Team versioning conventions / 2

  • How should we handle hotfixes?

  • Staging Jenkins jobs - nightly or manually triggered?

  • Should big major production releases include version code names?

  • How should we sync apps with database versioning?