Skip to content

Commit 88c7a08

Browse files
emcdGPT-5 Codex
emcd
and
GPT-5 Codex
committed
Split common tests and releases guidance.
Refactor shared tests and releases docs into language-neutral core guides and add Python-specific overlay guides under documentation/common. Co-Authored-By: GPT-5 Codex <gpt-5-codex@users.noreply.openai.com>
1 parent ca9c289 commit 88c7a08

4 files changed

Lines changed: 890 additions & 671 deletions

File tree

‎documentation/common/releases-python.rst‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
.. vim: set fileencoding=utf-8:
2+
.. -*- coding: utf-8 -*-
3+
.. +--------------------------------------------------------------------------+
4+
| |
5+
| Licensed under the Apache License, Version 2.0 (the "License"); |
6+
| you may not use this file except in compliance with the License. |
7+
| You may obtain a copy of the License at |
8+
| |
9+
| http://www.apache.org/licenses/LICENSE-2.0 |
10+
| |
11+
| Unless required by applicable law or agreed to in writing, software |
12+
| distributed under the License is distributed on an "AS IS" BASIS, |
13+
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
14+
| See the License for the specific language governing permissions and |
15+
| limitations under the License. |
16+
| |
17+
+--------------------------------------------------------------------------+
18+
19+
20+
*******************************************************************************
21+
Releases (Python)
22+
*******************************************************************************
23+
24+
This guide provides Python-specific release commands and workflows.
25+
For language-neutral release principles, see :doc:`releases`.
26+
27+
The project follows `semantic versioning <https://semver.org/>`_ for releases.
28+
29+
Release Process
30+
===============================================================================
31+
32+
Pre-Release Quality Check
33+
-------------------------------------------------------------------------------
34+
35+
Run local quality assurance before any release process::
36+
37+
git status && git pull origin master
38+
hatch --env develop run make-all
39+
40+
Also, ensure that at least one news fragment exists under
41+
``.auxiliary/data/towncrier``.
42+
43+
Initial Release Candidate
44+
-------------------------------------------------------------------------------
45+
46+
1. **Branch Setup**: Checkout ``master`` branch and ensure it's up to date::
47+
48+
git checkout master
49+
git pull origin master
50+
51+
2. **Create Release Branch**: Checkout new release branch::
52+
53+
git checkout -b release-<major>.<minor>
54+
55+
3. **Version Bump**: Bump alpha to release candidate and commit::
56+
57+
hatch version rc
58+
git commit -am "Version: $(hatch version)"
59+
60+
4. **Tag Release Candidate**::
61+
62+
git tag -m "Release candidate v$(hatch version)." v$(hatch version)
63+
64+
5. **Push Branch and Tag**: Push release branch and tag to upstream::
65+
66+
git push -u origin release-<major>.<minor>
67+
git push --tags
68+
69+
6. **Setup Next Development Cycle**: Return to ``master`` and prepare for next
70+
version::
71+
72+
git checkout master
73+
hatch version minor,alpha
74+
next_release="$(hatch version | sed 's/a[0-9]*$//')"
75+
git commit -am "Start of development for release ${next_release}."
76+
git tag -m "Start of development for release ${next_release}." "i${next_release}"
77+
git push origin master --tags
78+
79+
Final Release
80+
-------------------------------------------------------------------------------
81+
82+
1. **Branch Setup**: Checkout and update the release branch::
83+
84+
git checkout release-<major>.<minor>
85+
git pull origin release-<major>.<minor>
86+
87+
2. **Version Finalization**: Bump release candidate to final release::
88+
89+
hatch version release
90+
git commit -am "Version: $(hatch version)"
91+
92+
3. **Changelog Generation**: Run Towncrier to build final changelog::
93+
94+
hatch --env develop run towncrier build --keep --version $(hatch version)
95+
git commit -am "Update changelog for v$(hatch version)."
96+
97+
4. **Release Tag**: Create signed release tag::
98+
99+
git tag -m "<description>" v$(hatch version)
100+
101+
5. **Push Release**: Push release branch and tag to upstream::
102+
103+
git push origin release-<major>.<minor>
104+
git push --tags
105+
106+
6. **Monitor Release**: Wait for the release workflow to complete successfully.
107+
Check the GitHub Actions tab to monitor progress.
108+
109+
7. **Post-Release Cleanup**: Clean up news fragments and push::
110+
111+
git rm .auxiliary/data/towncrier/*.rst
112+
git commit -m "Clean up news fragments."
113+
git push origin release-<major>.<minor>
114+
115+
8. **Master Integration**: Cherry-pick release commits back to ``master``::
116+
117+
git checkout master
118+
git pull origin master
119+
git cherry-pick <changelog-commit-hash>
120+
git cherry-pick <cleanup-commit-hash>
121+
git push origin master
122+
123+
Use ``git log --oneline`` on the release branch to identify commit hashes.
124+
125+
Postrelease Patch
126+
-------------------------------------------------------------------------------
127+
128+
1. **Branch Setup**: Checkout and update the release branch::
129+
130+
git checkout release-<major>.<minor>
131+
git pull origin release-<major>.<minor>
132+
133+
2. **Patch Development**: Develop and test patch against branch.
134+
Add Towncrier entry and commit changes.
135+
136+
3. **Pre-Patch Validation**: Run quality checks to catch issues early::
137+
138+
hatch --env develop run linters
139+
140+
**Important**: Fix any linting errors before proceeding.
141+
142+
4. **Version Bump**: Bump to patch version and commit::
143+
144+
hatch version patch
145+
git commit -am "Version: $(hatch version)"
146+
147+
5. **Changelog Generation**: Run Towncrier to build patch changelog::
148+
149+
hatch --env develop run towncrier build --keep --version $(hatch version)
150+
git commit -am "Update changelog for v$(hatch version)."
151+
152+
6. **Patch Tag**: Create signed patch tag::
153+
154+
git tag -m "<description>" v$(hatch version)
155+
156+
7. **Push Patch**: Push release branch and tag to upstream::
157+
158+
git push origin release-<major>.<minor>
159+
git push --tags
160+
161+
8. **Monitor Release**: Wait for the release workflow to complete successfully.
162+
Check the GitHub Actions tab to monitor progress.
163+
164+
9. **Post-Release Cleanup**: Clean up news fragments and push::
165+
166+
git rm .auxiliary/data/towncrier/*.rst
167+
git commit -m "Clean up news fragments."
168+
git push origin release-<major>.<minor>
169+
170+
10. **Master Integration**: Cherry-pick patch commits back to ``master``::
171+
172+
git checkout master
173+
git pull origin master
174+
git cherry-pick <patch-commit-hash>
175+
git cherry-pick <changelog-commit-hash>
176+
git cherry-pick <cleanup-commit-hash>
177+
git push origin master
178+
179+
Use ``git log --oneline`` on the release branch to identify commit hashes.
180+
Resolve any conflicts as necessary during cherry-picking.
181+
182+
Changelog Entries
183+
===============================================================================
184+
185+
The project uses `Towncrier <https://towncrier.readthedocs.io/en/stable/>`_ to
186+
manage its changelog. When making changes that should be noted in the
187+
changelog, add a file ("fragment") to the ``.auxiliary/data/towncrier``
188+
directory with of ``<issue_number>.<type>.rst``, for changes with a Github
189+
issue, or ``+<title>.<type>.rst``, for changes without an associated issue
190+
number.
191+
192+
The entries will be collected and organized when a release is made, as
193+
described in the release process sections above.
194+
195+
Available Types
196+
-------------------------------------------------------------------------------
197+
198+
* ``enhance``: features and other improvements (documentation, platform
199+
support, etc...)
200+
* ``notify``: deprecations and other notices
201+
* ``remove``: removals of feature or platform support
202+
* ``repair``: bug fixes
203+
204+
Format
205+
-------------------------------------------------------------------------------
206+
207+
The file should contain a concise description of the change written in present
208+
tense. For example:
209+
210+
.. code-block:: rst
211+
:caption: .auxiliary/data/towncrier/+immutable-modules.enhance.rst
212+
213+
Add support for immutable module reclassification.
214+
215+
The description should:
216+
217+
* Start with a capital letter.
218+
* End with a period.
219+
* For multi-component or multi-faceted projects, a topic followed by colon may
220+
be used to introduce the content. (E.g., "Github Actions: ", "Copier
221+
Template: ").
222+
* Use present tense verbs in the imperative/subjunctive mood (e.g., "Add",
223+
"Fix", "Update") or simple noun phrases (e.g., "Support for <x>") in the
224+
introductory sentence.
225+
* If explanatory content is necessary, then it may be provided in the
226+
indicative mood using whatever verb tense is most natural to provide
227+
historical context or other rationale.
228+
* Focus on the what and why, not the how.
229+
* Be understandable by users, not just developers.
230+
* Acknowledge contributors.
231+
232+
Examples
233+
-------------------------------------------------------------------------------
234+
235+
Enhance:
236+
.. code-block:: rst
237+
:caption: .auxiliary/data/towncrier/457.enhance.rst
238+
239+
Improve release process documentation with Towncrier details.
240+
241+
Enhance:
242+
.. code-block:: rst
243+
:caption: .auxiliary/data/towncrier/458.enhance.rst
244+
245+
Add recursive module reclassification support.
246+
247+
Enhance:
248+
.. code-block:: rst
249+
:caption: .auxiliary/data/towncrier/459.enhance.rst
250+
251+
Support for Python 3.13.
252+
253+
Notice:
254+
.. code-block:: rst
255+
:caption: .auxiliary/data/towncrier/+exceptions.notify.rst
256+
257+
Deprecate ``OvergeneralException``. Package now raises more specific
258+
exceptions.
259+
260+
Remove:
261+
.. code-block:: rst
262+
:caption: .auxiliary/data/towncrier/460.remove.rst
263+
264+
Remove deprecated ``make_immutable`` function.
265+
266+
Repair:
267+
.. code-block:: rst
268+
:caption: .auxiliary/data/towncrier/456.repair.rst
269+
270+
Fix attribute visibility in immutable modules.

0 commit comments

Comments
 (0)