Version Control Usages¶
Abstract
The punch is deployed in production and subject to stringent development and validation procedures. This chapter explains the punch version scheme, and how it is implemented on top of the version control and build system.
Overview¶
Each release is identified by three digits major.minor.patch
majoridentifies a major release number.minoris increased whenever new features come in.patchis increased whenever a fix is delivered, resolving a reported and identified bug.
To make it easier to communicate, each punch major release is identified by logical name.
Brad refer to all 4.x releases, Craig to all 5.x releases, etc.. These logical names are only
indicative. They do not appear in the generated packages. For example a standalone package is named:
punch-standalone-6.2.0.zip
Production Releases¶
Version numbers have a very precise meaning when it comes to migrating or patching a platform. Here are the rules :
- a new
majorrelease requires a careful an planned migration strategy. A migration guide is provided, but it is nevertheless strongly advised to contact the punch expertise team. A typical example is a breaking change in one of the punch integrated database that may require some data migration strategy. - a new
minorrelease may incur some configuration changes. These are always documented as part of the punch documentation migration guides. - a new
patchrelease can safely be applied typically by customers directly using the punch tools and documentation. These are typically downloaded from the punch website.
Preview Releases¶
The punch is a state-of-the-art data analytics platform and new features come in regularly. It is common for customers to request to work on top of a candidate release to benefit from the latest features or improvements.
These releases are tagged with the a special version number 5.7.4-SNAPSHOT, 6.1.0-SNAPSHOT etc..
Patch Management¶
In this chapter we explain the complete punch process from a bug identification to the patch delivery in all the affected releases. For the sake of clarity we will assume a worst case situation where a bug in a past release is shown to affect many subsequent releases.
The starting situation is illustrated next with a number of production releases deployed by various customers. Here two major releases are highlighted 5.x (craig) and 6.x (dave).
Tip
The PunchPlatform source code is managed using Git and is available online at https://gitlab.thalesdigital.io/punch. The versioning is implemented using maven (https://maven.apache.org/). Note the usage of git branches for each minor releases, and git tags for each patch release.
Important
As illustrated, there is no 5.6 release. Thee gaps are normal. It frequently occur that a minor branch be deprecated typically when no customer use it anymore, in order to limit the number of supported releases.
Say a bug is identified in release 5.5.1. After analysis by the punch team, (say) the bug affects several releases. Here is the (example) impact analysis where each affected version is marked with an red symbol.
The punch team delivers a bug fix. This will consist in a new tagged release 5.5.3. The fix will be merged in all subsequent releases as well. The resulting situation is now.
All releases affected by the bug should be patched by all customers shortly. Because these patches are delivered for each minor branch, applying these patches to production platforms can be safely executed with or without the punch team assistance.
Important
Our development process ensures it is always safe and easy for a customers to patch its platform with a release from the same minor version. I.e. switching from (say) 5.3.4 to 5.3.7 will only bring in bug fixes or new features that have been certified as having no impact on existing platform.
New Releases¶
Whenever a new feature is available, the corresponding 'x' branch(es) are used to generate a new branch identified by a minor release number. A migration guide is provided to let customers switch to it and benefit from new features.