docs: create new document describing proposed release/branch management
What changed, and why it matters
This commit only adds a new documentation file explaining how the project plans to manage future software releases and branches. It does not change any program code, configuration, or security behavior. There is no security issue here.
No security action needed. Review as normal project documentation if desired.
Security signals we found
No strong security signals were identified.
Evidence from the diff
Commit 113aaf16 creates docs/release_branch_management.md, a 340-line markdown document describing LND’s proposed release/branch workflow: master stays open, release branches are created per major version, CI backports milestone-tagged PRs, version bumps happen in build/version.go, etc. The diff contains only documentation and mermaid diagrams; no source code, build scripts, CI definitions, or cryptographic logic are modified.
Changed components
Inspect captured patch +340 / −0
diff --git a/docs/release_branch_management.md b/docs/release_branch_management.md
new file mode 100644
index 0000000..0cf2020
--- /dev/null
+++ b/docs/release_branch_management.md
@@ -0,0 +1,340 @@
+# Release Branch Management
+
+## Overview
+
+This document describes the branch management workflow for lnd releases. The
+master branch remains open for merges at all times. Release stabilization
+happens on dedicated release branches, with CI automation handling backports of
+milestone-tagged changes. This approach maintains continuous development
+velocity while ensuring stable releases.
+
+## Branch Model Principles
+
+The release process operates on four core principles:
+
+**Master is always open.** Developers merge approved pull requests at any time
+without coordination around release windows. No merge freezes occur.
+
+**Each major release gets a dedicated branch.** When cutting a new major
+version, create a release branch from master. This branch handles all release
+candidates and subsequent patch releases for that version series.
+
+**CI automation handles backports.** Pull requests merged to master and tagged
+with a release milestone are automatically backported to the corresponding
+release branch. The automation creates backport PRs when conflicts occur.
+
+**Changes flow one direction only.** Changes move from master to release
+branches, never in reverse. Master always represents the latest development
+state.
+
+## Master Branch
+
+The master branch contains ongoing development work for future releases. It
+never freezes for releases.
+
+### Master Version Convention
+
+Master uses a `.99` patch version to indicate unreleased development work. After
+creating the `v0.21.x-branch` branch, update master's version in
+`build/version.go` to `0.21.99-beta`. This clearly signals post-0.21 but
+pre-0.22 code.
+
+When creating the next release branch (`v0.22.x-branch`), update master to
+`0.22.99-beta`. This pattern sorts correctly and is immediately recognizable as
+a development build.
+
+### Merging to Master
+
+Developers merge to master following normal review processes. If a change should
+be included in an active or upcoming release, tag the pull request with the
+appropriate milestone (`v0.21.0`, `v0.21.1`, etc.). The CI automation handles
+backporting after merge.
+
+No special coordination is required. Merge whenever the PR is approved,
+regardless of ongoing release activities. Initially manual input may be required
+to resolve conflicts that may arise. In the future LLM bots can help alleviate
+this manual work.
+
+## Major Release Process
+
+A major release introduces new features and represents a new minor version
+(e.g., 0.21.0, 0.22.0).
+
+### Creating the Release Branch
+
+When ready to begin a major release:
+
+1. Create a release branch from master: `git checkout -b v0.21.x-branch master`
+2. Push the branch: `git push origin v0.21.x-branch`
+3. Update `build/version.go` on the release branch to `0.21.0-beta.rc1`
+4. Commit the version bump: `git commit -am "build: bump version to v0.21.0-beta.rc1"`
+5. Update master's version to `0.21.99-beta` via a pull request
+6. Configure branch protection for `v0.21.x-branch` on GitHub
+
+### Release Candidate Cycle
+
+Create the first release candidate by tagging the version bump commit:
+
+```bash
+git tag -s v0.21.0-beta.rc1 -m "lnd v0.21.0-beta.rc1"
+git push origin v0.21.0-beta.rc1
+```
+
+This triggers CI to build release artifacts and Docker images.
+
+As testing uncovers issues, develop fixes on master and tag them with the
+`v0.21.0` milestone. Once merged, CI automation backports them to
+`v0.21.x-branch`. If backports apply cleanly, they merge automatically. If
+conflicts occur, CI creates backport PRs for manual resolution.
+
+When ready for the next release candidate:
+
+1. Create a pull request against the release branch to update `build/version.go` to `0.21.0-beta.rc2`
+2. After merging the PR, tag the merge commit on the release branch: `git tag -s v0.21.0-beta.rc2 -m "lnd v0.21.0-beta.rc2"`
+3. Push the new tag: `git push origin v0.21.0-beta.rc2`
+
+Repeat this cycle (rc3, rc4, etc.) until the release is stable.
+
+### Final Release
+
+For the final release, remove the RC suffix:
+
+1. Create a pull request against the release branch to update `build/version.go` to `0.21.0-beta`
+2. After merging the PR, tag the merge commit on the release branch: `git tag -s v0.21.0-beta -m "lnd v0.21.0-beta"`
+3. Push the new tag: `git push origin v0.21.0-beta`
+
+The `v0.21.x-branch` branch now enters maintenance mode for future patch
+releases.
+
+## Minor Release Process
+
+Minor (patch) releases fix bugs or security issues in released versions. They
+reuse the existing release branch for that version series.
+
+### Creating a Patch Release
+
+When a critical fix is needed for version 0.21.0:
+
+1. Develop and merge the fix to master
+2. Tag the PR with the `v0.21.1` milestone
+3. CI automation backports to `v0.21.x-branch`
+4. Create a pull request against the release branch to update `build/version.go` to `0.21.1-beta.rc1`
+5. After merging the PR, tag the merge commit: `git tag -s v0.21.1-beta.rc1 -m "lnd v0.21.1-beta.rc1"`
+6. Push the new tag: `git push origin v0.21.1-beta.rc1`
+
+If additional fixes are needed, follow the same process, incrementing through
+rc2, rc3, etc.
+
+For the final patch release:
+
+1. Create a pull request against the release branch to update `build/version.go` to `0.21.1-beta`
+2. After merging the PR, tag the merge commit: `git tag -s v0.21.1-beta -m "lnd v0.21.1-beta"`
+3. Push the new tag: `git push origin v0.21.1-beta`
+
+Multiple patch releases (0.21.1, 0.21.2, 0.21.3) can be created on the same
+`v0.21.x-branch` branch throughout the version's lifetime.
+
+## Manual Cherry-Picking
+
+Occasionally, a fix may be needed on a release branch that doesn't apply to
+master (release-specific issues, backports to older versions where master has
+diverged significantly, etc.).
+
+### When to Cherry-Pick Manually
+
+Cherry-pick directly to a release branch when:
+
+- The issue only exists on the release branch, not on master
+- Master's code has changed significantly, making a direct backport impractical
+- An urgent hotfix is needed before CI automation completes
+
+### Cherry-Pick Process
+
+```bash
+# Switch to the release branch
+git checkout v0.21.x-branch
+
+# Cherry-pick the commit from master
+git cherry-pick <commit-hash>
+
+# If conflicts occur, resolve them and continue
+git cherry-pick --continue
+```
+
+Cherry-picks still follow the normal PR flow, so a PR should be made only into
+the target release branch for normal review and CI.
+
+When manually cherry-picking, document why the normal backport flow was
+bypassed. If a corresponding change is needed on master (to prevent the bug from
+reappearing in future releases), ensure it's merged there as well.
+
+## Pull Request Milestones
+
+Developers use GitHub milestones to indicate which releases should include their
+changes.
+
+### Assigning Milestones
+
+When opening a PR, consider whether it should be backported to an active
+release:
+
+- **Bug fixes for active releases:** Assign the major release milestone (e.g.,
+`v0.21.0`)
+
+- **Critical fixes for older versions:** Assign the patch release milestone
+(e.g., `v0.20.3`)
+
+- **Features for future releases only:** No milestone, or assign the next major
+release milestone
+
+Milestones can be assigned at any time, even after merge. CI automation
+processes milestone-tagged PRs whenever they're detected.
+
+### Multiple Milestones
+
+If a fix needs to go into multiple release branches, assign multiple milestones
+to the PR. CI handles each backport independently. For example, a security fix
+might get both `v0.21.0` and `v0.20.3` milestones.
+
+## Backport Automation
+
+CI automation monitors merged PRs and backports milestone-tagged changes to the
+appropriate release branches. This section describes the automation's behavior.
+Implementation details are tracked in separate GitHub issues.
+
+### Automatic Backports
+
+When a PR with a release milestone merges to master:
+
+1. CI detects the milestone and identifies the target release branch
+2. CI attempts a three-way merge onto the release branch
+3. If successful, CI commits directly with a reference to the original PR
+4. The backported change appears in the next release candidate
+
+Developers don't need to take any action for successful backports.
+
+### Conflict Resolution
+
+When a backport conflicts:
+
+1. CI creates a new PR against the release branch
+2. The PR contains the attempted backport with conflict markers
+3. CI assigns the PR to the original author and notifies via GitHub mentions
+4. The author or maintainers resolve conflicts and merge the backport PR
+
+Backport PRs follow the normal review process and must pass all CI checks.
+
+### Monitoring Backports
+
+Track backport status through GitHub Projects or by filtering PRs. Backport PRs
+include labels indicating the original PR and milestone. Successfully backported
+commits reference the original PR in their commit messages.
+
+## Version Bump Timing
+
+Version numbers in `build/version.go` must be updated at specific points in the
+release process.
+
+**On release branches:** Update immediately before tagging. The commit that
+updates the version is the commit that gets tagged. This ensures built binaries
+report the correct version.
+
+**On master:** Update when creating a new release branch. Master moves from
+`0.20.99-beta` to `0.21.99-beta` when `v0.21-release` is created.
+
+**For each RC:** Increment the RC number before tagging. `0.21.0-beta.rc1` →
+`0.21.0-beta.rc2` → `0.21.0-beta.rc3`, etc.
+
+**For final releases:** Remove the RC suffix. `0.21.0-beta.rc5` → `0.21.0-beta`.
+
+## Branch Model Visualization
+
+The following diagrams illustrate the branch workflow and change flow.
+
+### Timeline View: Major Release Branch Lifecycle
+
+```mermaid
+gitGraph
+ commit id: "0.20.0 released"
+ commit id: "Feature A"
+ commit id: "Feature B"
+ branch v0.21.x-branch
+ commit id: "Version → 0.21.0-rc1" tag: "v0.21.0-beta.rc1"
+ checkout main
+ commit id: "Feature C (for 0.22)"
+ commit id: "Feature D (for 0.22)"
+ checkout v0.21.x-branch
+ commit id: "Backport: Fix X"
+ commit id: "Version → 0.21.0-rc2" tag: "v0.21.0-beta.rc2"
+ checkout main
+ commit id: "Feature E (for 0.22)"
+ commit id: "Fix Y (backport to 0.21)"
+ checkout v0.21.x-branch
+ commit id: "Backport: Fix Y"
+ commit id: "Version → 0.21.0" tag: "v0.21.0-beta"
+ checkout main
+ commit id: "Feature F (for 0.22)"
+ commit id: "Feature G (for 0.22)"
+ checkout v0.21.x-branch
+ commit id: "Backport: Critical fix Z"
+ commit id: "Version → 0.21.1-rc1" tag: "v0.21.1-beta.rc1"
+ commit id: "Version → 0.21.1" tag: "v0.21.1-beta"
+ checkout main
+ commit id: "Continue development"
+```
+
+After the v0.21.x-branch branch is created, both branches evolve independently.
+Master continues with features for future releases while the release branch
+focuses solely on stabilization and bug fixes.
+
+### Pull Request Flow with Milestone-Based Backports
+
+```mermaid
+flowchart TD
+ A[PR Merged to Master] --> B{Has Release<br/>Milestone?}
+ B -->|No| C[Done - Stays in Master Only]
+ B -->|Yes| D{Release Branch<br/>Exists?}
+ D -->|No| E[Queued for Future<br/>Release Branch]
+ D -->|Yes| F{First RC<br/>Tagged?}
+ F -->|No| G[Queued Until<br/>RC1 Tagged]
+ F -->|Yes| H[CI: Attempt<br/>Backport]
+ H --> I{Clean<br/>Apply?}
+ I -->|Yes| J[Auto-merge to<br/>Release Branch]
+ I -->|No| K[Create Backport PR<br/>for Manual Resolution]
+ J --> L[Done]
+ K --> M[Maintainer Resolves<br/>Conflicts]
+ M --> L
+```
+
+The milestone tag triggers the backport process. CI validates that the target
+release branch exists and has entered the RC phase before attempting backports.
+
+### Major vs Minor Release Branching
+
+```mermaid
+gitGraph
+ commit id: "Development"
+ commit id: "More work"
+ branch v0.21.x-branch
+ commit id: "v0.21.0-rc1" tag: "v0.21.0-beta.rc1"
+ commit id: "v0.21.0-rc2" tag: "v0.21.0-beta.rc2"
+ commit id: "v0.21.0 final" tag: "v0.21.0-beta"
+ checkout main
+ commit id: "Continue dev"
+ commit id: "More features"
+ checkout v0.21.x-branch
+ commit id: "Patch fix 1"
+ commit id: "v0.21.1" tag: "v0.21.1-beta"
+ commit id: "Patch fix 2"
+ commit id: "v0.21.2" tag: "v0.21.2-beta"
+ checkout main
+ commit id: "Keep developing"
+ branch v0.22.x-branch
+ commit id: "v0.22.0-rc1" tag: "v0.22.0-beta.rc1"
+ checkout main
+ commit id: "Future work"
+```
+
+The v0.21.x-branch branch serves both the initial 0.21.0 release and subsequent
+patch releases (0.21.1, 0.21.2). When 0.22 development is ready, a new
+v0.22.x-branch branch is created, and the cycle repeats.
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.