Skip to content

Commit f1ccb35

Browse files
tisniktisnik
authored
Merge pull request #1928 from tisnik/lcore-1642-branching-model
LCORE-1642: Branching model
2 parents b0aa6e6 + f29e7ce commit f1ccb35

6 files changed

Lines changed: 1634 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ See the full documentation at [`../README.md`](../README.md) or browse sub-pages
7777

7878
## Releasing
7979

80+
[Branching](https://lightspeed-core.github.io/lightspeed-stack/branching.html)
81+
8082
[Releasing](https://lightspeed-core.github.io/lightspeed-stack/releasing.html)
8183

8284
## Demos

‎docs/branching.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Branching
2+
3+
<!-- vim-markdown-toc GFM -->
4+
5+
* [Introduction](#introduction)
6+
* [Basic rules](#basic-rules)
7+
* [Release branch](#release-branch)
8+
* [Key points](#key-points)
9+
* [Semantic versioning](#semantic-versioning)
10+
* [Rules (concise)](#rules-concise)
11+
* [Benefits](#benefits)
12+
* [Branches naming](#branches-naming)
13+
* [Branching visualization](#branching-visualization)
14+
* [Feature and fix branches that are merged into the main branch](#feature-and-fix-branches-that-are-merged-into-the-main-branch)
15+
* [Cherry picking changes into release (stable) branch from the main branch](#cherry-picking-changes-into-release-stable-branch-from-the-main-branch)
16+
* [Multiple release branches, fixes made in fix branches](#multiple-release-branches-fixes-made-in-fix-branches)
17+
18+
<!-- vim-markdown-toc -->
19+
20+
## Introduction
21+
22+
Lightspeed Core Stack adopts a Git workflow that creates and maintains
23+
dedicated release branches for each published Lightspeed Core Stack version,
24+
and pair that with strict semantic versioning to clearly communicate the nature
25+
of each release.
26+
27+
## Basic rules
28+
29+
* For every formal release (major.minor.patch) a long-lived branch
30+
named is created to reflect the version (for example, release/0.6.0).
31+
32+
* Routine development occurs on main branch (as of today); only bug fixes,
33+
security patches, and approved backports are merged into the corresponding
34+
release branch or branches.
35+
36+
* Each change merged to a release branch must pass the same CI pipeline used
37+
for main branch, including unit, integration, and end-to-end tests, before
38+
being packaged.
39+
40+
* Semantic versioning is applied to all published artifacts:
41+
- Increment MAJOR for incompatible API changes.
42+
- Increment MINOR for backwards-compatible feature additions.
43+
- Increment PATCH for backwards-compatible bug fixes and security patches.
44+
45+
* Patch releases (e.g., 0.6.0 → 0.6.1) are cut from the release branch and
46+
tagged with the semantic version; release tags are reproducible and signed.
47+
48+
* Backport changes are cherry-picked or merged into the appropriate release
49+
branch and receive a patch-level version bump and changelog entry documenting
50+
the fix and any CVE identifiers.
51+
52+
* Merge and backport rules: require code review, automated tests, and QA
53+
approval; record the originating main commit(s) and rationale in the release
54+
branch.
55+
56+
* End-of-support or EOL for a release is recorded; no further patches are
57+
applied after EOL except by exception and with explicit approval.
58+
59+
This approach keeps ongoing development separate from maintenance work, ensures
60+
clear, predictable version numbers for consumers, and provides a repeatable
61+
process for issuing hotfixes and patch releases.
62+
63+
64+
65+
## Release branch
66+
67+
A release branch is a Git branch used to prepare a new production release. It
68+
stabilizes the codebase for final testing, bug fixes, and release-specific
69+
tasks without blocking ongoing feature development on main/develop. Those
70+
branches will have the following naming schema:
71+
72+
```text
73+
release/MAJOR.MINOR.PATCH
74+
```
75+
76+
77+
78+
### Key points
79+
80+
* Purpose: Freeze features, perform QA, apply release-only fixes, update
81+
version numbers, and prepare release notes.
82+
83+
* Lifespan: Short-to-medium lived—exists from when you decide to cut a release
84+
until the release is shipped and merged back.
85+
86+
* Target branches: Typically created from a main integration branch (e.g.,
87+
develop or main) and merged back into both main (or master) and develop (or
88+
the integration branch) after release.
89+
90+
* Typical tasks on the branch: final bug fixes, documentation, version bump,
91+
packaging, and deployment scripts.
92+
93+
* Naming: Use clear names like release/1.4.0 or release-2026-03-30.
94+
95+
* Benefits: Isolates release stabilization work, lets feature development
96+
continue on develop/main, and provides a clear point for builds and QA.
97+
98+
99+
100+
## Semantic versioning
101+
102+
Semantic Versioning (SemVer) is a versioning scheme that conveys meaning about
103+
changes in a release using a three-part number: MAJOR.MINOR.PATCH.
104+
105+
106+
107+
### Rules (concise)
108+
109+
* Format: MAJOR.MINOR.PATCH (e.g., 2.5.1).
110+
111+
* Increment MAJOR for incompatible API changes.
112+
113+
* Increment MINOR when you add backwards-compatible features.
114+
115+
* Increment PATCH for backwards-compatible bug fixes.
116+
117+
* Pre-release identifiers: append a hyphen and identifiers for unstable
118+
releases (e.g., 1.0.0-alpha.1).
119+
120+
* Build metadata: append a plus and metadata ignored for precedence (e.g.,
121+
1.0.0+20130313144700).
122+
123+
* Precedence: Compare MAJOR, then MINOR, then PATCH numerically; pre-release
124+
versions have lower precedence than the associated normal version.
125+
126+
127+
128+
### Benefits
129+
130+
* Communicates compatibility guarantees to users.
131+
132+
* Supports dependency resolution and predictable upgrades.
133+
134+
135+
136+
## Branches naming
137+
138+
| Branch | Description |
139+
|---------------|-------------------------------|
140+
| main | production-ready code |
141+
| release/x.y.z | release stabilization branch |
142+
| feature/* | new features |
143+
| hotfix/* | urgent production fixes |
144+
145+
NOTE: the actual proposal covers release branches only; feature and hotfix
146+
branch naming conventions are not covered here.
147+
148+
149+
## Branching visualization
150+
151+
### Feature and fix branches that are merged into the main branch
152+
153+
[branching_1](https://lightspeed-core.github.io/lightspeed-stack/branching_1.svg)
154+
155+
### Cherry-picking changes into release (stable) branch from the main branch
156+
157+
[branching_2](https://lightspeed-core.github.io/lightspeed-stack/branching_2.svg)
158+
159+
### Multiple release branches, fixes made in fix branches
160+
161+
[branching_3](https://lightspeed-core.github.io/lightspeed-stack/branching_3.svg)
162+

0 commit comments

Comments
 (0)