Skip to content

Commit 09c8821

Browse files
4gust4gust
authored
Create RELEASE_GUIDE.md (#880)
1 parent 1310fac commit 09c8821

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎RELEASE_GUIDE.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# MSAL Python — Release Guide
2+
3+
This document provides step-by-step instructions for releasing a new version of `msal` to PyPI.
4+
5+
---
6+
7+
## Prerequisites
8+
9+
- You have push access to the [AzureAD/microsoft-authentication-library-for-python](https://github.com/AzureAD/microsoft-authentication-library-for-python) repository.
10+
- The following GitHub repository secrets are configured:
11+
- `TEST_PYPI_API_TOKEN` — API token for [TestPyPI](https://test.pypi.org/)
12+
- `PYPI_API_TOKEN` — API token for [PyPI](https://pypi.org/)
13+
14+
---
15+
16+
## Version Location
17+
18+
The package version is defined in a single file:
19+
20+
```
21+
msal/sku.py → __version__ = "x.y.z"
22+
```
23+
24+
`setup.cfg` reads it dynamically via `version = attr: msal.__version__`, so **no other file needs updating**.
25+
26+
---
27+
28+
## Branch Strategy
29+
30+
```
31+
dev (all development happens here)
32+
│
33+
│── feature/fix PR → merged into dev
34+
│
35+
├──► release-1.35.0 (version branch, cut from dev when ready)
36+
│ │
37+
│ ├── TestPyPI publish (automatic on push)
38+
│ │
39+
│ ├── bug found? fix on dev, merge dev → release-1.35.0
40+
│ │ │
41+
│ │ └── TestPyPI re-publish (automatic)
42+
│ │
43+
│ ├── tag 1.35.0 (via GitHub Release) → PyPI publish
44+
│ │
45+
│ │ ── post-release hotfix needed? ──
46+
│ │
47+
│ ├── fix on dev, merge dev → release-1.35.0
48+
│ │ │
49+
│ │ ├── bump sku.py to 1.35.1
50+
│ │ │
51+
│ │ ├── TestPyPI re-publish (automatic)
52+
│ │ │
53+
│ │ └── tag 1.35.1 (via GitHub Release) → PyPI publish
54+
│ │
55+
│ └── (repeat for further patches: 1.35.2, 1.35.3, ...)
56+
│
57+
├──► release-1.36.0 (next minor version, cut from dev)
58+
│ │
59+
│ ├── TestPyPI publish
60+
│ │
61+
│ ├── tag 1.36.0 → PyPI publish
62+
│ │
63+
│ └── patches: merge dev → bump → tag 1.36.1, 1.36.2, ...
64+
...
65+
```
66+
67+
- **`dev`** — All feature work, bug fixes, and PRs land here.
68+
- **`release-x.y.z`** — Version branch cut from `dev` when ready to release. Used for final validation and TestPyPI testing.
69+
- **Tags** — Created from the version branch via GitHub Releases to trigger production PyPI publish.
70+
71+
---
72+
73+
## Step-by-Step Release Process
74+
75+
### 1. Complete All Work on `dev`
76+
77+
- All features, fixes, and version bumps should be merged into `dev` via PRs.
78+
- Ensure CI passes on `dev`.
79+
- Update the version in `msal/sku.py` before cutting the release branch:
80+
```python
81+
__version__ = "1.35.0"
82+
```
83+
84+
### 2. Create a Version Branch from `dev`
85+
86+
```bash
87+
git checkout dev
88+
git pull origin dev
89+
git checkout -b release-1.35.0
90+
git push origin release-1.35.0
91+
```
92+
93+
This push triggers the CD pipeline:
94+
- CI runs tests (must pass).
95+
- CD publishes to **TestPyPI** automatically.
96+
- Verify at: https://test.pypi.org/project/msal/
97+
98+
### 3. Apply Patches (If Needed)
99+
100+
If bugs are found during validation:
101+
102+
1. Fix the bug on `dev` first (via a PR to `dev`).
103+
2. Merge `dev` into the version branch:
104+
```bash
105+
git checkout release-1.35.0
106+
git merge dev
107+
git push origin release-1.35.0
108+
```
109+
3. This triggers another TestPyPI publish. Bump the version to `1.35.1` if the previous version was already published.
110+
111+
### 4. Create a GitHub Release (Production Publish)
112+
113+
Once the version branch is validated:
114+
115+
1. Go to **GitHub → Releases → Create a new release**.
116+
2. Click **"Choose a tag"** and type the version (e.g., `1.35.0`) — select **"Create new tag on publish"**.
117+
3. Set **Target** to the `release-1.35.0` branch.
118+
4. Set **Release title** to `1.35.0`.
119+
5. Add release notes (changelog, breaking changes, etc.).
120+
6. Click **"Publish release"**.
121+
122+
This creates a tag, which triggers the CD pipeline to publish to **PyPI**.
123+
124+
Verify at: https://pypi.org/project/msal/
125+
126+
### 5. Post-Release
127+
128+
- Verify installation: `pip install msal==1.35.0`
129+
- If the version on `dev` hasn't been bumped yet, open a PR to bump `msal/sku.py` to the next dev version (e.g., `1.36.0`).
130+
131+
---
132+
133+
## Hotfix Releases
134+
135+
For urgent fixes on an already-released version:
136+
137+
1. Fix the issue on `dev` (via PR).
138+
2. Merge `dev` into the existing `release-x.y.z` branch.
139+
3. Update `msal/sku.py` to the patch version (e.g., `1.35.0` → `1.35.1`).
140+
4. Push the version branch (triggers TestPyPI).
141+
5. Create a GitHub Release with tag `1.35.1` targeting `release-1.35.0`.
142+
143+
---
144+
145+
## How the CI/CD Pipeline Works
146+
147+
| Job | Trigger | Purpose |
148+
|-----|---------|---------|
149+
| **ci** | Every push and labeled PR to `dev` | Runs tests on Python 3.8–3.14 |
150+
| **cb** | After CI passes | Runs benchmarks |
151+
| **cd** | Push to `release-*` branch or tag | Builds and publishes the package |
152+
153+
| Trigger | Target |
154+
|---------|--------|
155+
| Push to `release-*` branch | **TestPyPI** |
156+
| Tag (created via GitHub Release) | **PyPI** (production) |
157+
158+
---
159+
160+
## Quick Reference
161+
162+
```bash
163+
# 1. Ensure dev is ready, version bumped in msal/sku.py
164+
# 2. Cut version branch
165+
git checkout dev && git pull
166+
git checkout -b release-1.35.0
167+
git push origin release-1.35.0
168+
# → TestPyPI publish happens automatically
169+
170+
# 3. If patches needed: fix on dev, then merge into release branch
171+
git checkout release-1.35.0
172+
git merge dev
173+
git push origin release-1.35.0
174+
175+
# 4. Production release: create a GitHub Release
176+
# → GitHub.com → Releases → New release
177+
# → Tag: 1.35.0, Target: release-1.35.0
178+
# → PyPI publish happens automatically
179+
```

0 commit comments

Comments
 (0)