|
| 1 | +# Versioning and Branching in Trustification |
| 2 | + |
| 3 | +This document outlines how we handle versioning in the Trustification |
| 4 | +organization. |
| 5 | + |
| 6 | +Individual projects inside the Trustification organization may have more specific |
| 7 | +rules and/or guidelines. |
| 8 | + |
| 9 | +# Overview |
| 10 | + |
| 11 | +Trustification follows [Semantic Versioning](https://semver.org/). This means that |
| 12 | +a version is expressed in the format X.Y.Z, where: |
| 13 | + |
| 14 | +- X is the major version, representing significant changes and new features |
| 15 | +- Y is the minor version, representing new features and improvements |
| 16 | +- Z is the patch version, representing bug fixes and minor improvements |
| 17 | + |
| 18 | +_NOTE_: If the major release is 0, any minor release may contain breaking changes. |
| 19 | + |
| 20 | +# Branching |
| 21 | + |
| 22 | +In order to maintain our guarantees two types of branches will be maintained: |
| 23 | +`main` and `release-X.Y`. |
| 24 | + |
| 25 | +- `main` branch is where all of the development happens. It is not guaranteed |
| 26 | + stable and may contain breaking changes. |
| 27 | +- `release-X.Y` where X.Y is the minor version for a release is considered |
| 28 | + stable. These branches will receive backport fixes for critical issues, but no |
| 29 | + new features will be added. |
| 30 | + |
| 31 | +# Releases |
| 32 | + |
| 33 | +All releases from the main branch will be marked as pre-release and be of the |
| 34 | +form `vX.Y.0-alpha.n`, where `X.Y` represents the next minor release and `n` |
| 35 | +follows Semantic Versioning precedence rules for pre-release. For example, |
| 36 | +if the next minor release is going to be 2.0, a pre-release from the main |
| 37 | +branch might be `v2.0.0-alpha.1` or `v2.0.0-alpha.2`, depending on the number of |
| 38 | +pre-releases that have been made so far. By marking releases from the main |
| 39 | +branch as pre-release, we aim to clearly indicate that the code may contain |
| 40 | +breaking changes and is not yet considered stable. |
| 41 | + |
| 42 | +Releases from `release-X.Y` branches contain stable code and always start with |
| 43 | +`vX.Y.0`. For example, the first release on a `release-2.3` branch would be |
| 44 | +`v2.3.0` and after critical issues are fixed + backported, the next release on |
| 45 | +the same branch would be `v2.3.1`. Marking these as full releases, we aim to |
| 46 | +indicate that they are stable, tested, and usable in production settings. |
| 47 | + |
| 48 | +_NOTE_ When we say release, we are referring to a |
| 49 | +[GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) |
| 50 | +and the associated git tag. |
| 51 | + |
| 52 | +# Pull Request (PR) Process |
| 53 | + |
| 54 | +Every PR should be annotated with an icon indicating whether it's |
| 55 | +a: |
| 56 | + |
| 57 | +- Breaking change: :warning: (`:warning:`) |
| 58 | +- Non-breaking feature: :sparkles: (`:sparkles:`) |
| 59 | +- Patch fix: :bug: (`:bug:`) |
| 60 | +- Docs: :book: (`:book:`) |
| 61 | +- Infra/Tests/Other: :seedling: (`:seedling:`) |
| 62 | +- No release note: :ghost: (`:ghost:`) |
| 63 | + |
| 64 | +Since GitHub supports emoji aliases (ie. `:ghost:`), there is no need to include |
| 65 | +the emoji directly in the PR title -- **please use the alias**. It used to be |
| 66 | +the case that projects using emojis for PR typing had to include the emoji |
| 67 | +directly because GitHub didn't render the alias. Given that `:warning:` is |
| 68 | +easy enough to read as text, easy to parse in release tooling, and rendered in |
| 69 | +GitHub well, we prefer to standardize on the alias. |
0 commit comments