Skip to content

Commit 8fff73e

Browse files
TransurgeonTransurgeon
committed
add a release instructions file
1 parent 035a0ce commit 8fff73e

1 file changed

Lines changed: 246 additions & 0 deletions

File tree

‎RELEASES.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Release Procedures
2+
3+
This file documents the procedures for releasing new versions of
4+
SparseDiffPy and its SparseDiffEngine submodule.
5+
Adapted from the [CVXPY release procedures](https://github.com/cvxpy/cvxpy/blob/master/PROCEDURES.md).
6+
7+
## Versioning
8+
9+
SparseDiffEngine's version is defined in `SparseDiffEngine/CMakeLists.txt`:
10+
11+
```cmake
12+
set(DIFF_ENGINE_VERSION_MAJOR X)
13+
set(DIFF_ENGINE_VERSION_MINOR Y)
14+
set(DIFF_ENGINE_VERSION_PATCH Z)
15+
```
16+
17+
SparseDiffPy's version is defined in `pyproject.toml`:
18+
19+
```toml
20+
version = "X.Y.Z"
21+
```
22+
23+
Both repos keep their versions in sync.
24+
25+
## Minor Release (e.g., 0.2.0)
26+
27+
A minor release increments the MINOR version and resets PATCH to 0.
28+
Always release SparseDiffEngine first, then SparseDiffPy.
29+
30+
### SparseDiffEngine
31+
32+
1. From `main`, create a release branch `release/X.Y.x`:
33+
```bash
34+
git checkout main
35+
git checkout -b release/X.Y.x
36+
```
37+
38+
2. Set the version to `X.Y.0` in `CMakeLists.txt`, commit, and tag:
39+
```bash
40+
# Edit CMakeLists.txt: MINOR = Y, PATCH = 0
41+
git add CMakeLists.txt
42+
git commit -m "Set version to X.Y.0 for release"
43+
git tag vX.Y.0
44+
```
45+
46+
3. Lay groundwork for the next patch release on this branch.
47+
Bump PATCH to 1 and commit. *Do not* tag this commit:
48+
```bash
49+
# Edit CMakeLists.txt: PATCH = 1
50+
git add CMakeLists.txt
51+
git commit -m "Begin X.Y.1 development"
52+
```
53+
54+
4. Switch to `main` and bump to the next minor version for development:
55+
```bash
56+
git checkout main
57+
# Edit CMakeLists.txt: MINOR = Y+1, PATCH = 0
58+
git add CMakeLists.txt
59+
git commit -m "Begin X.(Y+1).0 development cycle"
60+
```
61+
62+
5. Push everything:
63+
```bash
64+
git push origin release/X.Y.x
65+
git push origin main
66+
git push origin vX.Y.0
67+
```
68+
69+
### SparseDiffPy
70+
71+
6. **Wait for SparseDiffEngine CI to pass.** Check the workflow run at
72+
the [Actions tab](https://github.com/SparseDifferentiation/SparseDiffEngine/actions).
73+
Do not proceed until the Engine's GitHub Release has been created
74+
successfully.
75+
76+
7. From `main`, create a release branch and point the submodule at
77+
the Engine's tagged release:
78+
```bash
79+
git checkout -b release/X.Y.x
80+
cd SparseDiffEngine
81+
git checkout vX.Y.0
82+
cd ..
83+
```
84+
85+
8. Set the version to `X.Y.0` in `pyproject.toml`, commit, and tag:
86+
```bash
87+
# Edit pyproject.toml: version = "X.Y.0"
88+
git add SparseDiffEngine pyproject.toml
89+
git commit -m "Release vX.Y.0"
90+
git tag vX.Y.0
91+
```
92+
93+
9. Lay groundwork for the next patch. Bump version to `X.Y.1` and commit.
94+
*Do not* tag this commit:
95+
```bash
96+
# Edit pyproject.toml: version = "X.Y.1"
97+
git add pyproject.toml
98+
git commit -m "Begin X.Y.1 development"
99+
```
100+
101+
10. Switch to `main` and bump to the next minor version for development.
102+
Also update the submodule to track Engine's `main`:
103+
```bash
104+
git checkout main
105+
cd SparseDiffEngine
106+
git checkout main
107+
cd ..
108+
# Edit pyproject.toml: version = "X.(Y+1).0"
109+
git add SparseDiffEngine pyproject.toml
110+
git commit -m "Begin X.(Y+1).0 development cycle"
111+
```
112+
113+
11. Push everything:
114+
```bash
115+
git push origin release/X.Y.x
116+
git push origin main
117+
git push origin vX.Y.0
118+
```
119+
120+
## Patch Release (e.g., 0.2.1)
121+
122+
A patch release increments the PATCH version on an existing release branch.
123+
124+
### SparseDiffEngine
125+
126+
1. Checkout the release branch and cherry-pick fixes from `main`:
127+
```bash
128+
git checkout release/X.Y.x
129+
git cherry-pick <commit-hash>
130+
```
131+
132+
2. Set the version to `X.Y.Z` in `CMakeLists.txt`, commit, and tag:
133+
```bash
134+
# Edit CMakeLists.txt: PATCH = Z
135+
git add CMakeLists.txt
136+
git commit -m "Set version to X.Y.Z for release"
137+
git tag vX.Y.Z
138+
```
139+
140+
3. Lay groundwork for the next patch. Bump PATCH to Z+1, commit (no tag):
141+
```bash
142+
# Edit CMakeLists.txt: PATCH = Z+1
143+
git add CMakeLists.txt
144+
git commit -m "Begin X.Y.(Z+1) development"
145+
```
146+
147+
4. Push:
148+
```bash
149+
git push origin release/X.Y.x
150+
git push origin vX.Y.Z
151+
```
152+
153+
### SparseDiffPy
154+
155+
5. **Wait for SparseDiffEngine CI to pass.** Check the workflow run at
156+
the [Actions tab](https://github.com/SparseDifferentiation/SparseDiffEngine/actions).
157+
Do not proceed until the Engine's GitHub Release has been created
158+
successfully.
159+
160+
6. Checkout the release branch, cherry-pick or update bindings as needed,
161+
and point the submodule at the Engine's new tag:
162+
```bash
163+
git checkout release/X.Y.x
164+
cd SparseDiffEngine
165+
git checkout vX.Y.Z
166+
cd ..
167+
```
168+
169+
7. Set the version to `X.Y.Z` in `pyproject.toml`, commit, and tag:
170+
```bash
171+
# Edit pyproject.toml: version = "X.Y.Z"
172+
git add SparseDiffEngine pyproject.toml
173+
git commit -m "Release vX.Y.Z"
174+
git tag vX.Y.Z
175+
```
176+
177+
8. Lay groundwork for the next patch. Bump version to `X.Y.(Z+1)`, commit (no tag):
178+
```bash
179+
# Edit pyproject.toml: version = "X.Y.(Z+1)"
180+
git add pyproject.toml
181+
git commit -m "Begin X.Y.(Z+1) development"
182+
```
183+
184+
9. Push:
185+
```bash
186+
git push origin release/X.Y.x
187+
git push origin vX.Y.Z
188+
```
189+
190+
## Deployment
191+
192+
Deployments are automatically triggered by pushing a version tag (`v*`).
193+
194+
**SparseDiffEngine** (`.github/workflows/release.yml`):
195+
- Runs tests on Ubuntu and macOS
196+
- Creates a GitHub Release with auto-generated release notes
197+
198+
**SparseDiffPy** (`.github/workflows/build-and-publish.yml`):
199+
- Builds wheels for Python 3.11-3.14 on Ubuntu, macOS, and Windows
200+
- Publishes to TestPyPI first, then to PyPI
201+
202+
Progress can be monitored from the Actions tabs:
203+
- [SparseDiffEngine Actions](https://github.com/SparseDifferentiation/SparseDiffEngine/actions)
204+
- [SparseDiffPy Actions](https://github.com/SparseDifferentiation/SparseDiffPy/actions)
205+
206+
After a successful deployment, verify the package on
207+
[PyPI](https://pypi.org/project/sparsediffpy/).
208+
209+
### Example: deploying v0.2.0
210+
211+
After pushing the `v0.2.0` tag in SparseDiffEngine:
212+
213+
1. Go to [SparseDiffEngine Actions](https://github.com/SparseDifferentiation/SparseDiffEngine/actions).
214+
A workflow run labelled `v0.2.0` should appear. It will:
215+
- Run `all_tests` on Ubuntu and macOS
216+
- If both pass, create a GitHub Release at
217+
https://github.com/SparseDifferentiation/SparseDiffEngine/releases/tag/v0.2.0
218+
with auto-generated release notes
219+
220+
2. Once the Engine release succeeds, push the `v0.2.0` tag in SparseDiffPy.
221+
Go to [SparseDiffPy Actions](https://github.com/SparseDifferentiation/SparseDiffPy/actions).
222+
A workflow run labelled `v0.2.0` should appear. It will:
223+
- Build wheels for every Python 3.11-3.14 + OS combination
224+
- Publish all wheels and the sdist to
225+
[TestPyPI](https://test.pypi.org/project/sparsediffpy/)
226+
- After TestPyPI succeeds, publish to
227+
[PyPI](https://pypi.org/project/sparsediffpy/)
228+
229+
3. Verify the release landed:
230+
```bash
231+
pip install sparsediffpy==0.2.0
232+
python -c "import sparsediffpy; print('OK')"
233+
```
234+
235+
If the workflow fails intermittently (e.g., network timeouts), re-run it
236+
from the Actions tab. If code changes are required, you will need to
237+
delete the tag, fix the issue, re-tag, and push again.
238+
239+
## Notes
240+
241+
- Always release SparseDiffEngine first — SparseDiffPy depends on it
242+
via the git submodule.
243+
- The submodule pointer in SparseDiffPy must point at the exact tagged
244+
commit in SparseDiffEngine.
245+
- Push branches before tags so CI has access to the branch context.
246+
- Never tag a commit that has not been pushed to the remote.

0 commit comments

Comments
 (0)