Skip to content

An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.

docs(release): replace next branch with per-minor release branches

Andras Bacsai8ae3b9152c3b
diff --git a/AGENTS.md b/AGENTS.md
index fa5c428160..a57f2c2c4c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -235,8 +235,8 @@ The persistent-storage implementation is the reference pattern: `Project\Service
## Git Workflow
- Production branch: `main`
-- Development branch: `next`
-- Fix PRs should target the current production branch; feature PRs should target `next`
+- Development branch: `release/v4.x`, where `x` is the next minor release (for example, `release/v4.5` while production is `4.4.x`). Do not use `next`.
+- Fix PRs should target the current production branch; feature PRs should target the current `release/v4.x` branch
<laravel-boost-guidelines>
=== foundation rules ===
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 626f6d7b93..977b90919a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -193,11 +193,12 @@ Choose the branch based on the type of change:
| --- | --- | --- |
| Fixes and small improvements | `main` | `main` |
| Security fixes | `main` | `main` |
-| New features and larger changes | `next` | `next` |
+| New features and larger changes | `release/v4.x` | `release/v4.x` |
- For a fix, branch from `main` and target `main`.
-- For a feature, branch from `next` and target `next`.
-- If a fix is discovered while developing a feature, submit it separately to `main`. Maintainers will merge `main` into `next` so the fix is included there too.
+- For a feature, branch from `release/v4.x` and target `release/v4.x`.
+- `x` is the number of the next minor release. For example, when the production version is `4.4.x`, use `release/v4.5`. There is no `next` branch.
+- If a fix is discovered while developing a feature, submit it separately to `main`. Maintainers will merge `main` into `release/v4.x` so the fix is included there too.
- Pull requests targeting the wrong branch may be closed or asked to retarget.
diff --git a/RELEASE.md b/RELEASE.md
index 3733392a48..2a1c84cabd 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -5,52 +5,54 @@
| Branch | Purpose |
| --- | --- |
| `main` | Latest production source |
-| `next` | Feature integration and RC releases |
-| `feature/*` | New features based on and merged into `next` |
+| `release/v4.x` | Feature integration and RC releases for the next minor release, such as `release/v4.5` |
+| `feature/*` | New features based on and merged into the current `release/v4.x` branch |
| `hotfix/X.Y.Z` | Production fixes based on `main` |
+`x` is the number of the next minor release. When `4.4.x` is the production version, the release branch is `release/v4.5`. Create a new `release/v4.x` branch from `main` after each stable minor release. Do not use a long-lived `next` branch.
+
Release workflows never edit or commit versions. Stable versions come from `config/constants.php`; RC versions come from `coolify.nightly.version` in `versions.json` and `other/nightly/versions.json`.
## Where changes go
- Fixes, security updates, and small improvements target `main`.
-- New features and larger changes target `next`.
-- Merge `main` into `next` regularly so every production fix is included in the next release.
-- Do not merge `next` into `main` until an RC is approved for a stable release.
+- New features and larger changes target the current `release/v4.x` branch.
+- Merge `main` into `release/v4.x` regularly so every production fix is included in the next release.
+- Do not merge `release/v4.x` into `main` until an RC is approved for a stable release.
## Feature and RC flow
```text
-feature/* → next → RC
+feature/* → release/v4.x → RC
```
-1. Merge feature branches into `next`.
-2. Set `coolify.nightly.version` in both version files to the intended RC, such as `4.4-rc.1`.
-3. Regular `next` builds publish `sha-<short-sha>`, `4.4-rc.1.<short-sha>`, and the moving `next` tag. They never publish the exact `4.4-rc.1` tag.
-4. Create a reviewed draft GitHub Release named `v4.4-rc.1` and mark it as a prerelease.
-5. Run **Release Coolify RC** manually from `next` and enter `v4.4-rc.1`.
-6. The workflow validates the draft and configured nightly version, builds the exact RC, publishes `4.4-rc.1`, updates `next`, and publishes the draft prerelease.
+1. Merge feature branches into `release/v4.x`.
+2. Set `coolify.nightly.version` in both version files to the intended RC, such as `4.5-rc.1`.
+3. Regular `release/v4.x` builds publish `sha-<short-sha>`, `4.5-rc.1.<short-sha>`, and the moving `next` image tag. They never publish the exact `4.5-rc.1` tag.
+4. Create a reviewed draft GitHub Release named `v4.5-rc.1` and mark it as a prerelease.
+5. Run **Release Coolify RC** manually from `release/v4.x` and enter `v4.5-rc.1`.
+6. The workflow validates the draft and configured nightly version, builds the exact RC, publishes `4.5-rc.1`, updates the `next` image tag, and publishes the draft prerelease.
7. Advance `coolify.nightly.version` to the next intended RC version.
## Stable release flow
```text
-next → main → stable release
+release/v4.x → main → stable release
```
-1. Temporarily stop merging features into `next`.
-2. Change the version on `next` from the approved RC to the stable version, such as `4.4.0`.
-3. Merge `next` into `main`.
-4. Create a reviewed draft GitHub Release named `v4.4.0`.
+1. Temporarily stop merging features into `release/v4.x`.
+2. Change the version on `release/v4.x` from the approved RC to the stable version, such as `4.5.0`.
+3. Merge `release/v4.x` into `main`.
+4. Create a reviewed draft GitHub Release named `v4.5.0`.
5. Run the stable release workflow from `main`.
-6. The workflow rebuilds the exact stable version, publishes `4.4.0` and `latest`, then publishes the draft.
+6. The workflow rebuilds the exact stable version, publishes `4.5.0` and `latest`, then publishes the draft.
7. Update the CDN only after the release is approved.
-8. Advance `next` to the next development version.
+8. Create the next release branch from `main`, such as `release/v4.6`, and set its development version. Delete the old release branch.
## Hotfix flow
```text
-main → hotfix/X.Y.Z → main → next
+main → hotfix/X.Y.Z → main → release/v4.x
```
1. Create `hotfix/X.Y.Z` from `main` when a patch needs an integration branch. A single fix may use a normal branch from `main` instead.
@@ -59,7 +61,7 @@ main → hotfix/X.Y.Z → main → next
4. Merge the fix into `main`.
5. Create a reviewed draft GitHub Release named `vX.Y.Z`.
6. Run the stable release workflow from `main`.
-7. Merge `main` into `next`, resolve the version in favor of the next intended RC, and delete the hotfix branch if one was used.
+7. Merge `main` into `release/v4.x`, resolve the version in favor of the next intended RC, and delete the hotfix branch if one was used.
8. Update the CDN only after the release is approved.
## Image tags
@@ -67,9 +69,9 @@ main → hotfix/X.Y.Z → main → next
| Tag | Meaning |
| --- | --- |
| `latest` | Latest stable release |
-| `next` | Latest successful `next` build |
+| `next` | Latest successful `release/v4.x` build |
| `X.Y.Z` | Exact stable release |
| `X.Y-rc.N` | Exact RC release |
| `sha-<commit>` | Exact commit build |
-Git tags use the `v` prefix, such as `v4.4.0`. Docker image tags do not.
+Git tags use the `v` prefix, such as `v4.5.0`. Docker image tags do not.