You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The document outlines the steps to build and release the `deeptab` package. At this point, it is assumed that the development and testing of the package have been completed successfully.
3
+
The document outlines the steps to build and release the `deeptab` package. It is assumed that all feature branches and PRs for the release have been reviewed, approved, and merged into `main` before starting this process.
4
4
5
5
## Release workflow
6
6
@@ -15,83 +15,204 @@ The document outlines the steps to build and release the `deeptab` package. At t
It is expected from the contributor to update the documentation as an when required along side the change in source code. Please use the below process to test the documentation:
50
+
After all PRs for the release are merged into `main`, create a dedicated release branch.
50
51
51
-
```sh
52
-
cd docs/
52
+
```{important}
53
+
Always branch off from an up-to-date `main`. Never start a release from a stale local copy.
54
+
```
55
+
56
+
```bash
57
+
git checkout main && git pull
58
+
git checkout -b release/vX.Y.Z
59
+
git push -u origin release/vX.Y.Z
60
+
```
61
+
62
+
## 2. Apply hotfixes and documentation updates
63
+
64
+
Use the release branch to apply any last-minute bug fixes, dependency security patches, or documentation updates required before the release.
65
+
66
+
```{note}
67
+
Only **bug fixes and documentation changes** belong on the release branch. New features must target the next release cycle via `main`.
68
+
```
69
+
70
+
```{warning}
71
+
If you update any dependencies (e.g. to resolve security findings), regenerate the lock file immediately:
72
+
73
+
poetry update <package>
74
+
75
+
Then verify the change does not break any tests.
76
+
```
77
+
78
+
**Security audit** — run `pip-audit` and resolve any vulnerability with an available fix before bumping the version:
79
+
80
+
```bash
81
+
poetry run pip-audit
82
+
```
83
+
84
+
Vulnerabilities with no upstream fix available should be noted and tracked as known accepted risks.
85
+
86
+
## 3. Quality checks
53
87
54
-
make doctest
88
+
Run all checks in the order shown below. **Each step must pass cleanly before proceeding to the next.**
89
+
90
+
### 3.1 Linting
91
+
92
+
```bash
93
+
just lint
55
94
```
56
95
57
-
Fix any docstring related issue, then proceed with next steps.
96
+
Runs `ruff check --fix` and auto-corrects fixable issues. Review and manually resolve any remaining errors.
58
97
59
-
## 2. Version update
98
+
### 3.2 Formatting
99
+
100
+
```bash
101
+
just format
102
+
```
60
103
61
-
See **[Versioning](versioning.md)** for the full explanation of SemVer rules, commit types, and how `cz bump` works. The commands are summarised below.
104
+
Runs `ruff format` to ensure consistent code style across the codebase.
62
105
63
-
**For a stable release** — let `cz bump` derive the next version automatically from conventional commits:
106
+
### 3.3 Pre-commit hooks
64
107
65
108
```bash
66
-
cz bump
109
+
just check
110
+
```
111
+
112
+
Runs all pre-commit hooks across all files: ruff lint/format, prettier (YAML/Markdown/JSON), and Pyright type checking.
113
+
114
+
```{important}
115
+
If `just check` modifies any files, stage and commit them before continuing:
A test failure at this stage must be fixed on the release branch before proceeding. Do not skip, suppress, or comment out failing tests.
130
+
```
131
+
132
+
## 4. Documentation
133
+
134
+
Build the HTML docs locally. Sphinx treats all warnings as errors (`-W`), so every warning must be resolved before proceeding.
135
+
136
+
```bash
137
+
just docs
138
+
```
139
+
140
+
Review the rendered output in `docs/_build/html/`. Check for broken links, missing API entries, and any rendering issues on new or changed pages.
141
+
142
+
```{note}
143
+
See the **[Documentation Guide](documentation.md)** for docstring conventions and tips on building docs locally.
144
+
```
145
+
146
+
## 5. Commit all changes
147
+
148
+
Once all checks and the documentation build pass cleanly, stage and commit any outstanding changes:
149
+
150
+
```bash
151
+
git add -A
152
+
git commit -m "chore(release): pre-release fixes and QA for vX.Y.Z"
153
+
git push origin release/vX.Y.Z
154
+
```
155
+
156
+
```{note}
157
+
Prefer `just commit` over a manual `git commit` to stay consistent with the conventional commit style enforced by commitizen.
158
+
```
159
+
160
+
## 6. Version bump
161
+
162
+
```{important}
163
+
Always run `--dry-run` first and review the proposed CHANGELOG entries carefully before applying the bump.
164
+
```
165
+
166
+
**Step 1 — preview:**
167
+
168
+
```bash
169
+
poetry run cz bump --dry-run
170
+
```
171
+
172
+
Inspect the output:
173
+
174
+
- The proposed increment (MAJOR / MINOR / PATCH) matches expectations
175
+
- The CHANGELOG entries are complete and correctly classified
176
+
- There are no duplicate entries (can happen when multiple commits share identical messages)
177
+
178
+
**Step 2 — apply:**
179
+
180
+
```bash
181
+
poetry run cz bump
67
182
```
68
183
69
184
This will:
70
185
71
-
- Determine the next version from conventional commits since the last tag
72
-
- Update the version in `pyproject.toml`
73
-
- Update `CHANGELOG.md`
74
-
- Create a local commit `bump: version X.Y.Z-1 → X.Y.Z`
186
+
- Update `version` in `pyproject.toml`
187
+
- Append the new section to `CHANGELOG.md`
188
+
- Create a local commit: `bump: version X.Y.Z-1 → X.Y.Z`
75
189
76
-
**For a release candidate** — set the version explicitly (e.g. `1.7.0rc1`):
190
+
**Step 3 — review the bump commit:**
77
191
78
192
```bash
79
-
poetry version 1.7.0rc1
80
-
poetry lock
193
+
git show HEAD
194
+
```
195
+
196
+
Check that `pyproject.toml` shows the correct version and that `CHANGELOG.md` reads cleanly. Manually amend duplicate entries if present, then push:
197
+
198
+
```bash
199
+
git push origin release/vX.Y.Z
81
200
```
82
201
83
-
Then update `CHANGELOG.md` manually and commit:
202
+
**For a release candidate** — set the version explicitly instead of using `cz bump`:
84
203
85
204
```bash
205
+
poetry version X.Y.ZrcN
206
+
poetry lock
86
207
git add pyproject.toml poetry.lock CHANGELOG.md
87
-
git commit -m "bump: version 1.6.1 → 1.7.0rc1"
208
+
git commit -m "bump: version X.Y.Z-1 → X.Y.ZrcN"
88
209
```
89
210
90
-
The version number follows the format `major.minor.patch` for stable, or `major.minor.patchrcN` for release candidates.
211
+
See **[Versioning](versioning.md)** for the full SemVer rules and commit-type reference.
91
212
92
-
## 3. Tag and publish a release candidate
213
+
## 7. Tag and publish a release candidate
93
214
94
-
RC tags are pushed **directly from the release branch** — no PR to `main` required.
215
+
RC tags are pushed **directly from the release branch** — no PR to `main`is required.
95
216
96
217
```bash
97
218
git tag -a vX.Y.ZrcN -m "Release candidate vX.Y.ZrcN"
@@ -100,36 +221,48 @@ git push origin vX.Y.ZrcN
100
221
101
222
This triggers `publish-testpypi.yml`, which publishes to **TestPyPI** and creates a GitHub pre-release.
102
223
103
-
If issues are found, fix them on the release branch, bump to the next RC (`rcN+1`), and repeat.
224
+
If issues are found, fix them on the release branch (return to step 2), bump to the next RC (`rcN+1`), and repeat.
104
225
105
-
## 4. Release PR (stable only)
226
+
## 8. Release PR (stable only)
106
227
107
-
Once all RCs are approved, open a PR from `release/vX.Y.Z` to `main`:
228
+
Once all RCs are approved (or skipping RC for a straightforward release), open a PR from `release/vX.Y.Z` to `main` on GitHub.
108
229
109
230
- After review and approval, merge the PR
110
231
-**Merging to `main` does NOT trigger a PyPI release**
111
232
112
-
> **Promoting a model from experimental to stable?** Verify the [Model Promotion Policy](model_promotion_policy.md) checklist is complete before merging a release PR that includes a promotion.
233
+
```{important}
234
+
**Promoting a model from experimental to stable?** Verify the [Model Promotion Policy](model_promotion_policy.md) checklist is complete before merging a release PR that includes a promotion.
235
+
```
113
236
114
-
## 5. Create and push the stable tag
237
+
## 9. Create and push the stable tag
115
238
116
-
After the release PR is merged:
239
+
After the release PR is merged into `main`:
117
240
118
241
```bash
119
242
git checkout main && git pull
120
243
git tag -a vX.Y.Z -m "Release vX.Y.Z"
121
244
git push origin vX.Y.Z
122
245
```
123
246
124
-
## 6. Publish package
247
+
```{warning}
248
+
Pushing the tag triggers PyPI publication immediately and cannot be undone. Confirm that `main` is in the expected state and the version in `pyproject.toml` is correct before pushing.
249
+
```
250
+
251
+
## 10. Publish package
125
252
126
-
The tag push automatically triggers the appropriate GitHub Actions workflow — see **[CI/CD](ci_cd.md)** for the full workflow details. In summary:
253
+
The tag push automatically triggers the appropriate GitHub Actions workflow — see **[CI/CD](ci_cd.md)** for full details. In summary:
0 commit comments