> For the complete documentation index, see [llms.txt](https://jadelab.gitbook.io/jadegit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jadelab.gitbook.io/jadegit/0.18.0/ci-cd/branching-strategy.md).

# Branching Strategy

JadeGit is agnostic of the branching strategy used. The build process is based on comparing commits, meaning it works regardless of how branches are structured. The strategies described here may suit teams introducing CI/CD pipelines around JadeGit, and form the basis for the examples used throughout this section.

## Main Branch

`main` represents the next uncut release. It remains stable and suitable as the basis for a release at any point. Bugs found in `main` are fixed directly, or addressed via a new feature branch if the scope warrants it.

## Feature Branches

Development work is organised around `feature/*` branches. A feature branch is created for each piece of work and merged into `main` via a pull request once it has been tested and signed off. Solution design and general implementation should be validated at this stage — this is what keeps `main` stable. Once merged, any changes in requirements are addressed via a new feature branch rather than modifying work already in `main`.

```mermaid
gitGraph
   commit
   commit
   branch feature/flux-capacitor order: 2
   checkout feature/flux-capacitor
   commit
   commit
   commit
   checkout main
   merge feature/flux-capacitor id: "PR merge"
   commit
```

## Release Branches

`release/*` branches are cut from `main` when a release is being prepared, and provide a stable point for final testing before a release is tagged. Once testing is complete, the release branch is tagged, which can be used to trigger deployment to staging and subsequently production. All production versions are represented by tags, providing a clear and auditable record of what has been deployed.

```mermaid
gitGraph
   commit
   commit
   branch feature/flux-capacitor order: 2
   checkout feature/flux-capacitor
   commit
   commit
   commit
   checkout main
   merge feature/flux-capacitor id: "PR merge"
   commit
   branch release/1.0 order: 3
   checkout release/1.0
   commit
   commit tag: "v1.0.0"
```

### Hot Fixes

When a bug is found after a release branch has been cut — whether during final testing or after it has been tagged and deployed — a hot fix may be required, the approach depending on whether it also needs to be applied to `main`:

* If `main` also needs the fix, a `hotfix/*` branch is created from `main`, the fix is added and merged back into `main` via a pull request, then cherry-picked onto the release branch
* If the code in `main` has already diverged — meaning the bug no longer exists there or the same fix cannot be cherry-picked — a `hotfix/*` branch is created from the release branch, the fix is added and merged back into the release branch via a pull request

Once all outstanding fixes have been applied and re-testing is complete, the release branch can be re-tagged for the next production release.

```mermaid
gitGraph
   commit
   branch feature/flux-capacitor order: 2
   checkout feature/flux-capacitor
   commit
   commit
   commit
   checkout main
   merge feature/flux-capacitor id: "PR merge"
   branch release/1.0 order: 3
   checkout main
   commit
   branch hotfix/lightning-rod order: 2
   checkout release/1.0
   commit tag: "v1.0.0"
   checkout hotfix/lightning-rod
   commit id: "hotfix"
   checkout main
   commit
   merge hotfix/lightning-rod id: "PR merge 2"
   checkout release/1.0
   cherry-pick id: "hotfix" tag: "v1.0.1"
```

## Continuous Release

As automated testing matures and release frequency increases, teams may find they can tag `main` directly rather than maintaining a release branch. This approach relies on `main` being stable and releasable at all times, with automated testing providing the confidence needed to release without a dedicated stabilisation period.

```mermaid
gitGraph
   commit
   branch feature/mr-fusion order: 2
   checkout feature/mr-fusion
   commit
   commit
   checkout main
   merge feature/mr-fusion id: "PR merge" tag: "v2.0"
   branch feature/hover-conversion order: 2
   checkout feature/hover-conversion
   commit
   commit
   checkout main
   merge feature/hover-conversion id: "PR merge 2" tag: "v2.1"
```

### Hot Fixes

If a hot fix is required, the preferred approach is to fix on `main` and tag a new release as normal. However, if `main` contains structural changes that require an offline deployment and the hot fix can and needs to be released online immediately, a `hotfix/*` branch may be created from the last release tag instead. Once the fix has been implemented and tested, it should be merged back into `main` via a pull request so it is reviewed before tagging the hot fix branch for immediate release. In the unlikely event the code in `main` has already diverged, completing a pull request will need to be skipped, but the changes should still be reviewed before tagging the hot fix branch for release.

```mermaid
gitGraph
   commit tag: "v2.0"
   branch feature/hover-conversion order: 2
   checkout feature/hover-conversion
   commit
   commit
   checkout main
   merge feature/hover-conversion id: "PR merge" tag: "v2.1"
   branch hotfix/time-circuit-macrochip order: 3
   branch feature/train-track-adapter order: 2
   checkout feature/train-track-adapter
   commit
   commit
   checkout main
   merge feature/train-track-adapter id: "PR merge 2"
   checkout hotfix/time-circuit-macrochip
   commit id: "hotfix" tag: "v2.1.1"
   checkout main
   merge hotfix/time-circuit-macrochip id: "PR merge 3"
```

## Environments

The following environments represent a typical path to production, each serving a distinct purpose in the release lifecycle. Deployments to these environments can be triggered automatically based on the associated branch or tag.

| Name       | Branch / Tag         | Purpose                                                                                                            |
| ---------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Test       | `main`               | <p>• Early preview of upcoming changes<br>• Automated testing<br>• Manual testing (if required)</p>                |
| Preview    | `release/*`          | <p>• Preview of changes pending release<br>• Automated testing<br>• Manual testing (if required)<br>• Training</p> |
| Staging    | `v*`                 | • Production rehearsal                                                                                             |
| Production | `v*` (after Staging) | • Live environment                                                                                                 |

{% hint style="info" %}
Aside from hot fixes, manual testing may not be required in these environments when teams have shifted formal system and user acceptance testing left to the feature branch stage.
{% endhint %}

### Branches

Testing feature branches in isolation before merging into `main` requires environments separate from those on the path to production. When only one feature needs to be tested at a time, a feature branch can be deployed directly to one of these environments.

When there are a limited number of environments available, or feature changes need to be tested in combination before being individually merged into `main`, an `environment/<name>` branch can be used to combine and deploy multiple feature branches to the `<name>` environment.

Feature branches should always be created from `main` to keep them isolated. Environment branches serve purely as a testing surface and can be discarded and recreated as needed without affecting the integrity of the underlying feature branches.

```mermaid
gitGraph
   commit tag: "v2.1"
   branch hotfix/time-circuit-macrochip order: 2
   checkout hotfix/time-circuit-macrochip
   commit id: "design"
   checkout main
   branch environment/1885-wild-west order: 4
   checkout environment/1885-wild-west
   commit id: "mine-found"
   merge hotfix/time-circuit-macrochip id: "delorean-hidden"
   branch environment/1955-hill-valley order: 5
   checkout environment/1955-hill-valley
   commit id: "discovered"
   checkout hotfix/time-circuit-macrochip
   commit id: "implemented"
   checkout environment/1955-hill-valley
   merge hotfix/time-circuit-macrochip id: "88mph"
   checkout environment/1885-wild-west
   merge environment/1955-hill-valley id: "temporal-displacement"
   checkout main
   merge hotfix/time-circuit-macrochip id: "PR merge"
   branch feature/train-track-adapter order: 3
   checkout feature/train-track-adapter
   commit
   commit
   checkout environment/1885-wild-west
   merge feature/train-track-adapter id: "merge train-track-adapter"
```

{% hint style="warning" icon="screwdriver-wrench" %}
Environment branches may be considered an anti-pattern. The experimental [`--merge` build option](/jadegit/0.18.0/console/build.md#merging) is intended to provide a simpler solution for deploying multiple feature branches to a shared environment.
{% endhint %}