# Gerbil Trebuchet Versioning Guidelines

## 1 - General Guidelines

### 1.1 - Applicability

These guidelines are intended to take effect after version 1.0 of the CommonLine module is released. Prior to that, the CommonLine module is still considered to be in an alpha or pre-release status.

### 1.2 - Reducing the impact of breaking changes

#### 1.2.1 - Definitions

A breaking change is any change to the CL module that would:

* Require one or more implementations to make changes in order to prevent an error
* Result in a loss of existing functionality to an implementation

#### 1.2.2 - Deprecate changed interfaces and features when possible

When changes to external interfaces/features are required, GT will attempt to release the updated code as a minor version, while maintaining compatibility with the previous interface/feature. The existing interface/feature will be marked as deprecated in the changelog, and support will be dropped with the next major version release. If it is not possible to deprecate existing usages, the change will be delayed until the next major release, and implementations will be given advance notice.

#### 1.2.3 - Consolidate breaking changes into major releases

Breaking changes will only me made as part of a major version release, and those releases will be planned and coordinated ahead of time.

The CL team will maintain a long-term branch for the next major version. That branch will incorporate all bug-fixes and non-breaking features from the current major version, as well as any breaking changes that have been completed. The branch will be made available for implementations to use in a beta or pre-release state.

#### 1.2.4 - Examples:

Example #1:

_The CommonLine module is currently on version 1.12. An update is made to the payload emitted by the `commonline.lender.exceptionHandled.notify` event, removing one property and adding another. A new interface is created with an appropriately similar name as the old interface, and, if possible, our code is adjusted to make use of either interface. The new interface is released as part of version 1.13, and the changelog notes that the old interface is now deprecated. Implementations are encouraged to update their usages as soon as possible. Some time later version CommonLine releases version 2.0. At that time, the old interface will be removed and no longer supported._

Example #2:

_CommonLine has released version 1.05. In order to eliminate some tech debt, the GT team upgrades an internal package to a new version. The new version of the package introduces breaking changes in a manner that can not be supported alongside the old version. CommonLine will make these changes on a 2.0 branch that is being maintained. Implementations may (but are not required to) preview these changes by using the beta 2.0 build. GT will note the upcoming change in the changelog for version 1.06. Sometime later, GT will release version 2.0 and the old version of the library will no longer be supported._

### 1.3 - Limited support for non-current releases

#### 1.3.1 - Normal bug fixes

All non-critical bug fixes will be made using the latest minor version. Unless the fix is especially important, the fix will be available with the next minor release, which will occur at the end of GT's current sprint.

If a fix is needed sooner, GT will release a mid-sprint patch.

Normal bug fixes will not be retroactively applied to any previous minor versions.

#### 1.3.2 - Critical bug fixes and security vulnerabilities

In addition to being fixed on the latest minor version, critical bug fixes will be cherry-picked to previous minor versions that are actively used by deployments in production. These fixes will require coordination between GT and the affected implementation teams, as we do not actively track which specific version an implementation may be using.

GT will tag each minor release. If a critical bug fix needs to be retroactively applied, we will create new branches based off of the impacted minor release tags, apply the critical fix, and increment the patch number.

It is expected that implementations will pin their CommonLine packages to at least a minor-compatible version so that they will receive the critical update automatically.

#### 1.3.3 - Alpha builds

Alpha builds will be deprecated. Implementations are expected to pin to either a major or minor version.

#### 1.3.4 - New Features
All new features will be released via a new minor version. Multiple features may be bundled together into a single minor release.

Generally, a new minor version will be released at the end of each sprint. If a new feature is especially important or needed quickly, a minor version can be released mid-sprint.

#### 1.3.5 - Examples

Example 1:

_The current version of common line is `2.12`. A bug causing a display glitch is discovered and worked in the current sprint. AcmeBank is currently pinning version `^2.12` of the CommonLine library. They have a demo coming up in a couple of days and would like the display glitch fixed. GT fixes the issue and releases version `2.12.1` mid-sprint. AcmeBank will automatically receive the fix. At then end of the sprint, GT will release version `2.13`, which incorporates both the fix as well as a couple of new features. The bug fix will not be applied to any previous releases._

Example 2:

_CommonLine has just released version `1.18`. AcmeBank is currently pined on `~1.12`, and their end-to-end testing has revealed an edge case where a loan can be sent for approval without a borrower signature. After some Teams discussion between AcmeBank and GT, it is determined that the edge case could occur in production, and that a critical fix is needed. GT verifies that the bug is present on the current 1.18 release and fixes it. GT then makes a new branch called `release-1.12.01` that is based on the `1.12` tag and cherry-picks the fix. Information about the bug is posted and it is discovered that NeonBank is also affected. NeonBank is on version `1.15` and GT follows a similar process to create a new branch and cherry-pick the fix._

Example 3:

_CommonLine has been working on a new feature that will automatically create beautiful, interactive flow charts showing the status of an application. The new feature does not break any existing functionality and is released at the end of the sprint as version `3.09`. AcmeBank is currently pinned on version `~3.02`. They will have to update to `~3.09` to have see the new charts. NeonBank is pinned to version `^3.02` and automatically gets the new charts once released._

## 2 - Git flows

### 2.1 - General git flow for a sprint

### 2.2 - Working a breaking change

### 2.3 - Cherry-picking critical fixes