Skip to content

Commit 95be3cc

Browse files
acrocaacroca
committed
Documented release process
Signed-off-by: Albert Callarisa <albert@diagrid.io>
1 parent adbcf32 commit 95be3cc

File tree

1 file changed

+198
-0
lines changed

1 file changed

+198
-0
lines changed

‎RELEASE.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Release process
2+
3+
This document describes the release process for the Dapr Python SDK.
4+
It covers all packages published from this repository:
5+
6+
| Tag prefix | PyPI package |
7+
|---|---|
8+
| `v*` | `dapr` (core SDK) |
9+
| `workflow-v*` | `dapr-ext-workflow` |
10+
| `grpc-v*` | `dapr-ext-grpc` |
11+
| `fastapi-v*` | `dapr-ext-fastapi` |
12+
| `flask-v*` | `flask_dapr` |
13+
| `langgraph-v*` | `dapr-ext-langgraph` |
14+
| `strands-v*` | `dapr-ext-strands` |
15+
16+
## Overview
17+
18+
Releases follow a branching model where `main` is always the development trunk.
19+
When a version is ready to enter stabilisation, a `release-X.Y` branch is forked from `main`.
20+
From that point on, all changes land in `main` first and are backported to the release branch
21+
as needed. Release candidates and the final stable release are all cut from that branch.
22+
23+
```
24+
main ──●──●──●──●──●──●──●──●──●──●──▶
25+
│ (prev).dev X.Y.0.dev
26+
│ (fork) ↑
27+
release-X.Y ●──●────●───●───●───●──▶
28+
│ ↑ ↑ ↑
29+
│ rc0 rc1 X.Y.0
30+
│
31+
first commit on release-X.Y:
32+
- versions (prev).dev → X.Y.0rc0
33+
- dapr deps >=(prev).dev → >=X.Y.0rc0
34+
simultaneously on main:
35+
- versions (prev).dev → X.Y.0.dev
36+
- dapr deps >=(prev).dev → >=X.Y.0.dev
37+
```
38+
39+
## Version files
40+
41+
Every package in this repository has one version file and, for extensions, one `setup.cfg`
42+
dependency line that must be kept in sync during a release.
43+
44+
**Version files** (set `__version__`):
45+
- `dapr/version/version.py`
46+
- `ext/dapr-ext-workflow/dapr/ext/workflow/version.py`
47+
- `ext/dapr-ext-grpc/dapr/ext/grpc/version.py`
48+
- `ext/dapr-ext-fastapi/dapr/ext/fastapi/version.py`
49+
- `ext/dapr-ext-langgraph/dapr/ext/langgraph/version.py`
50+
- `ext/dapr-ext-strands/dapr/ext/strands/version.py`
51+
- `ext/flask_dapr/flask_dapr/version.py`
52+
53+
**Dependency lower bounds** in extension `setup.cfg` files (each has `dapr >= <version>`):
54+
- `ext/dapr-ext-workflow/setup.cfg`
55+
- `ext/dapr-ext-grpc/setup.cfg`
56+
- `ext/dapr-ext-fastapi/setup.cfg`
57+
- `ext/dapr-ext-langgraph/setup.cfg`
58+
- `ext/dapr-ext-strands/setup.cfg`
59+
- `ext/flask_dapr/setup.cfg`
60+
61+
## Version string conventions
62+
63+
| Stage | `__version__` example | dep lower bound example |
64+
|---|---|---|
65+
| Development (always on `main`) | `1.17.0.dev` | `dapr >= 1.17.0.dev` |
66+
| First RC (on `release-X.Y`) | `1.17.0rc0` | `dapr >= 1.17.0rc0` |
67+
| Subsequent RCs (on `release-X.Y`) | `1.17.0rc1`, `1.17.0rc2`, … | `dapr >= 1.17.0rc1` |
68+
| Stable release | `1.17.0` | `dapr >= 1.17.0` |
69+
| Patch release candidate | `1.17.1rc1` | `dapr >= 1.17.1rc1` |
70+
| Stable patch release | `1.17.1` | `dapr >= 1.17.1` |
71+
72+
## Remote convention
73+
74+
All commands below use `upstream` to refer to the **canonical Dapr repository**
75+
(`https://github.com/dapr/python-sdk`), not your personal fork.
76+
If your local remote is named differently, substitute accordingly.
77+
78+
## Scenario A — Fork a new release branch
79+
80+
Perform this when the current `main` is ready to start the stabilisation cycle for version X.Y.
81+
82+
### 1. Create the branch
83+
84+
```bash
85+
git checkout main
86+
git pull upstream main
87+
git checkout -b release-X.Y
88+
git push upstream release-X.Y
89+
```
90+
91+
### 2. Bump versions on the release branch (first commit)
92+
93+
On the newly created `release-X.Y` branch, open a PR **targeting `release-X.Y`** that does:
94+
95+
- In all seven version files: change `X.Y.0.dev` → `X.Y.0rc0`
96+
- In all six extension `setup.cfg` files: change `dapr >= X.Y.0.dev` → `dapr >= X.Y.0rc0`
97+
98+
### 3. Bump versions on `main` (second commit)
99+
100+
Open a PR targeting `main` to align it with the new release version:
101+
102+
- In all seven version files: change the previous dev version to `X.Y.0.dev`
103+
- In all six extension `setup.cfg` files: change the previous `dapr >= ...dev` to `dapr >= X.Y.0.dev`
104+
105+
### 4. Push the tags
106+
107+
Once the version bump PR on `release-X.Y` is merged, create and push the tags from the
108+
**tip of `release-X.Y`**:
109+
110+
```bash
111+
git checkout release-X.Y
112+
git pull upstream release-X.Y
113+
114+
git tag vX.Y.0rc0 && git push upstream vX.Y.0rc0
115+
git tag workflow-vX.Y.0rc0 && git push upstream workflow-vX.Y.0rc0
116+
git tag grpc-vX.Y.0rc0 && git push upstream grpc-vX.Y.0rc0
117+
git tag flask-vX.Y.0rc0 && git push upstream flask-vX.Y.0rc0
118+
git tag fastapi-vX.Y.0rc0 && git push upstream fastapi-vX.Y.0rc0
119+
git tag langgraph-vX.Y.0rc0 && git push upstream langgraph-vX.Y.0rc0
120+
git tag strands-vX.Y.0rc0 && git push upstream strands-vX.Y.0rc0
121+
```
122+
123+
Each tag push triggers the `dapr-python-release` workflow which builds and uploads the
124+
corresponding package to PyPI.
125+
126+
## Scenario B — Ship a new release candidate
127+
128+
Perform this when you want to publish `X.Y.0rcN` (N ≥ 1) from an existing `release-X.Y` branch.
129+
130+
### 1. Bump versions on the release branch
131+
132+
Open a PR **targeting `release-X.Y`** that does:
133+
134+
- In all seven version files: change `X.Y.0rc(N-1)` → `X.Y.0rcN`
135+
- In all six extension `setup.cfg` files: change `dapr >= X.Y.0rc(N-1)` → `dapr >= X.Y.0rcN`
136+
137+
### 2. Push the tags
138+
139+
Once the PR is merged:
140+
141+
```bash
142+
git checkout release-X.Y
143+
git pull upstream release-X.Y
144+
145+
git tag vX.Y.0rcN && git push upstream vX.Y.0rcN
146+
git tag workflow-vX.Y.0rcN && git push upstream workflow-vX.Y.0rcN
147+
git tag grpc-vX.Y.0rcN && git push upstream grpc-vX.Y.0rcN
148+
git tag flask-vX.Y.0rcN && git push upstream flask-vX.Y.0rcN
149+
git tag fastapi-vX.Y.0rcN && git push upstream fastapi-vX.Y.0rcN
150+
git tag langgraph-vX.Y.0rcN && git push upstream langgraph-vX.Y.0rcN
151+
git tag strands-vX.Y.0rcN && git push upstream strands-vX.Y.0rcN
152+
```
153+
154+
## Scenario C — Ship the stable release (and patch releases)
155+
156+
Perform this when `release-X.Y` is ready to ship a stable version — whether that is the
157+
initial `X.Y.0` or a patch release (`X.Y.1`, `X.Y.2`, …).
158+
159+
### 1. Bump versions on the release branch
160+
161+
Open a PR **targeting `release-X.Y`** that does:
162+
163+
- In all seven version files: change `X.Y.ZrcN` → `X.Y.Z` (drop the `rcN` suffix)
164+
- In all six extension `setup.cfg` files: change `dapr >= X.Y.ZrcN` → `dapr >= X.Y.Z`
165+
166+
### 2. Push the tags
167+
168+
Once the PR is merged:
169+
170+
```bash
171+
git checkout release-X.Y
172+
git pull upstream release-X.Y
173+
174+
git tag vX.Y.Z && git push upstream vX.Y.Z
175+
git tag workflow-vX.Y.Z && git push upstream workflow-vX.Y.Z
176+
git tag grpc-vX.Y.Z && git push upstream grpc-vX.Y.Z
177+
git tag flask-vX.Y.Z && git push upstream flask-vX.Y.Z
178+
git tag fastapi-vX.Y.Z && git push upstream fastapi-vX.Y.Z
179+
git tag langgraph-vX.Y.Z && git push upstream langgraph-vX.Y.Z
180+
git tag strands-vX.Y.Z && git push upstream strands-vX.Y.Z
181+
```
182+
183+
## Backporting changes
184+
185+
Bug fixes and small improvements that should appear in both `main` and an active release
186+
branch are backported automatically.
187+
188+
1. Open your PR targeting `main` as usual.
189+
2. Once merged, add a label of the form `backport release-X.Y` to the PR.
190+
The [backport workflow](.github/workflows/backport.yaml) will open a new PR against
191+
`release-X.Y` automatically.
192+
3. Review and merge the backport PR on `release-X.Y`.
193+
194+
You can also add the label before merging; the workflow will start once the PR is closed
195+
as merged.
196+
197+
> The backport workflow can target any `release-*` branch, so patches can be applied to
198+
> older releases if needed.

0 commit comments

Comments
 (0)