diff --git a/docs/README.md b/docs/README.md index 01752c21f..bf668b7a4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -77,6 +77,8 @@ See the full documentation at [`../README.md`](../README.md) or browse sub-pages ## Releasing +[Branching](https://lightspeed-core.github.io/lightspeed-stack/branching.html) + [Releasing](https://lightspeed-core.github.io/lightspeed-stack/releasing.html) ## Demos diff --git a/docs/branching.md b/docs/branching.md new file mode 100644 index 000000000..06ed06133 --- /dev/null +++ b/docs/branching.md @@ -0,0 +1,162 @@ +# Branching + + + +* [Introduction](#introduction) +* [Basic rules](#basic-rules) +* [Release branch](#release-branch) + * [Key points](#key-points) +* [Semantic versioning](#semantic-versioning) + * [Rules (concise)](#rules-concise) + * [Benefits](#benefits) +* [Branches naming](#branches-naming) +* [Branching visualization](#branching-visualization) + * [Feature and fix branches that are merged into the main branch](#feature-and-fix-branches-that-are-merged-into-the-main-branch) + * [Cherry picking changes into release (stable) branch from the main branch](#cherry-picking-changes-into-release-stable-branch-from-the-main-branch) + * [Multiple release branches, fixes made in fix branches](#multiple-release-branches-fixes-made-in-fix-branches) + + + +## Introduction + +Lightspeed Core Stack adopts a Git workflow that creates and maintains +dedicated release branches for each published Lightspeed Core Stack version, +and pair that with strict semantic versioning to clearly communicate the nature +of each release. + +## Basic rules + +* For every formal release (major.minor.patch) a long-lived branch + named is created to reflect the version (for example, release/0.6.0). + +* Routine development occurs on main branch (as of today); only bug fixes, + security patches, and approved backports are merged into the corresponding + release branch or branches. + +* Each change merged to a release branch must pass the same CI pipeline used + for main branch, including unit, integration, and end-to-end tests, before + being packaged. + +* Semantic versioning is applied to all published artifacts: + - Increment MAJOR for incompatible API changes. + - Increment MINOR for backwards-compatible feature additions. + - Increment PATCH for backwards-compatible bug fixes and security patches. + +* Patch releases (e.g., 0.6.0 → 0.6.1) are cut from the release branch and + tagged with the semantic version; release tags are reproducible and signed. + +* Backport changes are cherry-picked or merged into the appropriate release + branch and receive a patch-level version bump and changelog entry documenting + the fix and any CVE identifiers. + +* Merge and backport rules: require code review, automated tests, and QA + approval; record the originating main commit(s) and rationale in the release + branch. + +* End-of-support or EOL for a release is recorded; no further patches are + applied after EOL except by exception and with explicit approval. + +This approach keeps ongoing development separate from maintenance work, ensures +clear, predictable version numbers for consumers, and provides a repeatable +process for issuing hotfixes and patch releases. + + + +## Release branch + +A release branch is a Git branch used to prepare a new production release. It +stabilizes the codebase for final testing, bug fixes, and release-specific +tasks without blocking ongoing feature development on main/develop. Those +branches will have the following naming schema: + +```text +release/MAJOR.MINOR.PATCH +``` + + + +### Key points + +* Purpose: Freeze features, perform QA, apply release-only fixes, update + version numbers, and prepare release notes. + +* Lifespan: Short-to-medium lived—exists from when you decide to cut a release + until the release is shipped and merged back. + +* Target branches: Typically created from a main integration branch (e.g., + develop or main) and merged back into both main (or master) and develop (or + the integration branch) after release. + +* Typical tasks on the branch: final bug fixes, documentation, version bump, + packaging, and deployment scripts. + +* Naming: Use clear names like release/1.4.0 or release-2026-03-30. + +* Benefits: Isolates release stabilization work, lets feature development + continue on develop/main, and provides a clear point for builds and QA. + + + +## Semantic versioning + +Semantic Versioning (SemVer) is a versioning scheme that conveys meaning about +changes in a release using a three-part number: MAJOR.MINOR.PATCH. + + + +### Rules (concise) + +* Format: MAJOR.MINOR.PATCH (e.g., 2.5.1). + +* Increment MAJOR for incompatible API changes. + +* Increment MINOR when you add backwards-compatible features. + +* Increment PATCH for backwards-compatible bug fixes. + +* Pre-release identifiers: append a hyphen and identifiers for unstable + releases (e.g., 1.0.0-alpha.1). + +* Build metadata: append a plus and metadata ignored for precedence (e.g., + 1.0.0+20130313144700). + +* Precedence: Compare MAJOR, then MINOR, then PATCH numerically; pre-release + versions have lower precedence than the associated normal version. + + + +### Benefits + +* Communicates compatibility guarantees to users. + +* Supports dependency resolution and predictable upgrades. + + + +## Branches naming + +| Branch | Description | +|---------------|-------------------------------| +| main | production-ready code | +| release/x.y.z | release stabilization branch | +| feature/* | new features | +| hotfix/* | urgent production fixes | + +NOTE: the actual proposal covers release branches only; feature and hotfix +branch naming conventions are not covered here. + + +## Branching visualization + +### Feature and fix branches that are merged into the main branch + +[branching_1](https://lightspeed-core.github.io/lightspeed-stack/branching_1.svg) + +### Cherry-picking changes into release (stable) branch from the main branch + +[branching_2](https://lightspeed-core.github.io/lightspeed-stack/branching_2.svg) + +### Multiple release branches, fixes made in fix branches + +[branching_3](https://lightspeed-core.github.io/lightspeed-stack/branching_3.svg) + diff --git a/docs/branching_1.svg b/docs/branching_1.svg new file mode 100644 index 000000000..c84bd9d66 --- /dev/null +++ b/docs/branching_1.svg @@ -0,0 +1,376 @@ + + + + + + + + + + + + + + + + + + +
+
+
branch: fix F1
+
+
+ + branch: fix F1 + + + + + + + + + + + + + + + + + + +
+
+
main
+
+
+ + main + + + + + + + + + + + + + + + + + + + +
+
+
branch: fix F2
+
+
+ + branch: fix F2 + + + + + + + + + + + + +
+
+
m+1
+
+
+ + m+1 + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
m+2
+
+
+ + m+2 + + + + + + + + + + + + + +
+
+
merged branch F2
+
+
+ + merged branch F2 + + + + + + + + + + + + +
+
+
F2
+
+
+ + F2 + + + + + + + + + + + + + + + + + + +
+
+
m+3
+
+
+ + m+3 + + + + + + + + + + + + + + + + + + +
+
+
m+4
+
+
+ + m+4 + + + + + + + + + + + + + + + + + + +
+
+
m+5
+
+
+ + m+5 + + + + + + + + + + + + + + + + + + +
+
+
F1
+
+
+ + F1 + + + + + + + + + + + + + +
+
+
merged branch F1
+
+
+ + merged branch F1 + + + + + + + + + + + + +
+
+
F1.1
+
+
+ + F1.1 + + + + + + + + + + + + + + + + + + +
+
+
F3
+
+
+ + F3 + + + + + + + + + + + + + +
+
+
merged branch F3
+
+
+ + merged branch F3 + + + + + + + + + + + + +
+
+
F3.1
+
+
+ + F3.1 + + + + + + + + diff --git a/docs/branching_2.svg b/docs/branching_2.svg new file mode 100644 index 000000000..71f6b7edf --- /dev/null +++ b/docs/branching_2.svg @@ -0,0 +1,420 @@ + + + + + + + + + + + + + + + + + + +
+
+
release 0.5.0
+
+
+ + release 0.5.0 + + + + + + + + + + + + + + + + + + +
+
+
main
+
+
+ + main + + + + + + + + + + + + + + + + + + +
+
+
m+1
+
+
+ + m+1 + + + + + + + + + + + + + + + + + + +
+
+
m+2
+
+
+ + m+2 + + + + + + + + + + + + + + + + + + +
+
+
0.5.0
+
+
+ + 0.5.0 + + + + + + + + + + + + + +
+
+
release 0.5.1
+
+
+ + release 0.5.1 + + + + + + + + + + + + +
+
+
0.5.0r
+
+
+ + 0.5.0r + + + + + + + + + + + + + +
+
+
cherrypick F1
+
+
+ + cherrypick F1 + + + + + + + + + + + + + + + + + + +
+
+
m+3
+
+
+ + m+3 + + + + + + + + + + + + + + + + + + +
+
+
m+4
+
+
+ + m+4 + + + + + + + + + + + + + + + + + + +
+
+
0.5.1
+
+
+ + 0.5.1 + + + + + + + + + + + + + + + + + + +
+
+
m+5
+
+
+ + m+5 + + + + + + + + + + + + + + + + + + + +
+
+
cherrypick F2
+
+
+ + cherrypick F2 + + + + + + + + + + + + +
+
+
m+6
+
+
+ + m+6 + + + + + + + + + + + + + +
+
+
release 0.5.2
+
+
+ + release 0.5.2 + + + + + + + + + + + + +
+
+
0.5.2r
+
+
+ + 0.5.2r + + + + + + + + + + + + +
+
+
0.5.3
+
+
+ + 0.5.3 + + + + + + + + + + + + + + + + + + +
+
+
m+7
+
+
+ + m+7 + + + + + + + + diff --git a/docs/branching_3.svg b/docs/branching_3.svg new file mode 100644 index 000000000..4f0708106 --- /dev/null +++ b/docs/branching_3.svg @@ -0,0 +1,672 @@ + + + + + + + + + + + + + + + + + + +
+
+
release 0.5.0
+
+
+ + release 0.5.0 + + + + + + + + + + + + + + + + + + +
+
+
main
+
+
+ + main + + + + + + + + + + + + + + + + + + + +
+
+
branch: fix F1
+
+
+ + branch: fix F1 + + + + + + + + + + + + +
+
+
m+1
+
+
+ + m+1 + + + + + + + + + + + + + + + + + + +
+
+
m+2
+
+
+ + m+2 + + + + + + + + + + + + + + + + + + +
+
+
0.5.0
+
+
+ + 0.5.0 + + + + + + + + + + + + + +
+
+
release 0.5.1
+
+
+ + release 0.5.1 + + + + + + + + + + + + +
+
+
0.5.0r
+
+
+ + 0.5.0r + + + + + + + + + + + + + +
+
+
merged branch F1
+
+
+ + merged branch F1 + + + + + + + + + + + + +
+
+
F1
+
+
+ + F1 + + + + + + + + + + + + + +
+
+
cherrypick F1
+
+
+ + cherrypick F1 + + + + + + + + + + + + + + + + + + +
+
+
m+3
+
+
+ + m+3 + + + + + + + + + + + + + + + + + + + +
+
+
release 0.6.0
+
+
+ + release 0.6.0 + + + + + + + + + + + + +
+
+
m+4
+
+
+ + m+4 + + + + + + + + + + + + + + + + + + + +
+
+
branch: fix F2
+
+
+ + branch: fix F2 + + + + + + + + + + + + +
+
+
0.5.1
+
+
+ + 0.5.1 + + + + + + + + + + + + + + + + + + + +
+
+
backport change
+
+
+ + backport change + + + + + + + + + + + + +
+
+
m+5
+
+
+ + m+5 + + + + + + + + + + + + + + + + + + +
+
+
0.6.0
+
+
+ + 0.6.0 + + + + + + + + + + + + + + + + + + +
+
+
m+6
+
+
+ + m+6 + + + + + + + + + + + + + + + + + + +
+
+
0.5.1
+
+
+ + 0.5.1 + + + + + + + + + + + + + +
+
+
release 0.5.2
+
+
+ + release 0.5.2 + + + + + + + + + + + + +
+
+
0.5.2r
+
+
+ + 0.5.2r + + + + + + + + + + + + + +
+
+
merged branch F2
+
+
+ + merged branch F2 + + + + + + + + + + + + +
+
+
F2
+
+
+ + F2 + + + + + + + + + + + + +
+
+
0.5.3
+
+
+ + 0.5.3 + + + + + + + + + + + + + +
+
+
release 0.6.1
+
+
+ + release 0.6.1 + + + + + + + + + + + + +
+
+
0.6.0r
+
+
+ + 0.6.0r + + + + + + + + + + + + + + + + + + +
+
+
0.6.1
+
+
+ + 0.6.1 + + + + + + + + + + + + + + + + + + +
+
+
m+7
+
+
+ + m+7 + + + + + + + + diff --git a/docs/index.md b/docs/index.md index e23371a02..03b07a3ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -86,6 +86,8 @@ product questions using backend LLM services, agents, and RAG databases. ## Releasing +[Branching](https://lightspeed-core.github.io/lightspeed-stack/branching.html) + [Releasing](https://lightspeed-core.github.io/lightspeed-stack/releasing.html) ## Demos