Skip to content

Commit 271a720

Browse files
vitormattosvitormattos
committed
docs(release): replace future planning sections with actionable checklist steps
Remove the 'Automation candidates' and 'Suggested future helper commands' sections, which described potential improvements rather than concrete steps. Absorb the two genuinely actionable items directly into the checklist: - Add a git ls-remote command to confirm the stable branch HEAD SHA before creating the GitHub release tag. - Add a gh api command to verify the milestone was correctly renamed from 'Next Patch (XX)' to the versioned title before writing the release body. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
1 parent 7eba7b4 commit 271a720

File tree

1 file changed

+238
-14
lines changed

1 file changed

+238
-14
lines changed

‎developer_manual/release-process.rst‎

Lines changed: 238 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,48 @@ Release process
44
Resuming the steps:
55

66
1. Identify the next version number of all releases.
7-
2. Create the changelog of all branches that will be released.
8-
You will need to create the changelog in the :code:`CHANGELOG.md` file from the :code:`main` branch and then backport it to the stable branches.
9-
3. Make the necessary changes into the codebase to prepare the release.
7+
2. Collect and validate PRs from the commits since the previous release.
8+
3. Create the changelog for all branches that will be released.
9+
Write entries in :code:`CHANGELOG.md` on :code:`main`, then backport to stable branches.
10+
4. Verify version consistency across configuration files (:code:`appinfo/info.xml`, :code:`package.json`, :code:`package-lock.json`).
11+
5. Apply the required release changes in the codebase.
1012

1113
.. note::
1214
You can use the :code:`[skip ci]` tag in the commit message to skip the CI checks for the backport PRs to make the process faster.
1315

14-
4. Create a pull request to the `main` branch with the changes that you made.
15-
5. After the CI finish with success and the PR is merged, backport the changes to the stable branches that will be released.
16-
6. After the backport PRs are merged, create the releases in GitHub.
17-
7. Verify that the GitHub Action that creates the packages and publish them in the Nextcloud App Store finish with success.
18-
8. Announce the release in the Telegram channel.
16+
.. important::
17+
18+
Release PRs must stay strictly scoped to the release itself.
19+
Do not mix release automation, workflow, Release Drafter, refactor,
20+
or any other maintenance changes in the same PR.
21+
The allowed changes in a release PR are the changelog section and the
22+
version bumps required for that release.
23+
24+
6. Open a pull request to :code:`main` with the release preparation changes.
25+
7. After CI passes and the PR is merged, backport the changes to the stable branches to be released.
26+
8. After the backport PRs are merged, perform a smoke test on all supported browsers.
27+
9. Create the GitHub release for the oldest stable version in the cycle first.
28+
10. Verify the GitHub Action for that release finished successfully and wait until the version is visible in the Nextcloud App Store.
29+
11. Repeat the same publication and validation flow for the next newer stable version, one by one.
30+
12. Announce the release in the Telegram channel.
31+
32+
.. important::
33+
34+
When publishing more than one stable release in the same cycle, never
35+
create the newer tag before the older release is fully published.
36+
The required order is:
37+
38+
1. publish the oldest stable release
39+
2. wait for the GitHub Action to succeed
40+
3. confirm the version is visible on https://apps.nextcloud.com/apps/libresign/
41+
4. only then publish the next newer stable release
42+
43+
.. note::
44+
45+
If you automate release creation with :code:`gh release create` or
46+
:code:`gh release edit`, prefer loading the notes from a file instead of
47+
inlining multiline markdown in the shell command. This avoids escaping
48+
issues in backticks, parentheses, and links.
1949

2050
Version numbers
2151
---------------
@@ -25,6 +55,118 @@ Version numbers
2555
- ``MINOR`` is used for LibreSign feature releases.
2656
- ``PATCH`` is used for bug fixes or small improvements.
2757

58+
Milestones
59+
----------
60+
61+
Every PR must be assigned to a milestone.
62+
63+
- PRs targeting :code:`main` must use the current **major milestone** for the
64+
Nextcloud server version supported by :code:`appinfo/info.xml` on :code:`main`.
65+
- PRs targeting stable branches must use the corresponding **patch milestone**
66+
for that server major, using the branch :code:`appinfo/info.xml` version as the
67+
source of truth.
68+
69+
Examples with the current branch model:
70+
71+
- :code:`main` with :code:`14.0.0-dev.*` maps to :code:`Next Major (34)`.
72+
- :code:`stable33` maps to :code:`Next Patch (33)`.
73+
- :code:`stable32` maps to :code:`Next Patch (32)`.
74+
75+
.. important::
76+
77+
A PR without milestone is not ready for review or merge.
78+
Before opening or updating a release PR, confirm the milestone is correct.
79+
80+
Identifying the previous release tag
81+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82+
83+
Before starting the changelog, you need to identify the previous release tag for each stable branch:
84+
85+
.. code-block:: bash
86+
87+
# List all tags sorted by version (newest first)
88+
git tag -l "v*" --sort=-version:refname | head -20
89+
90+
# Or find the last tag for a specific branch
91+
git describe --tags --abbrev=0 stable22
92+
93+
This tag will be used in the commit log range when collecting PRs (e.g., ``v12.2.0..stable22``).
94+
95+
.. important::
96+
97+
The tag range is only the **raw input** for the changelog. On stable branches,
98+
it is possible to merge backports of already published hotfixes after the tag
99+
was created. Because of that, always cross-check the raw compare output with
100+
the existing published sections in :code:`CHANGELOG.md` and exclude entries
101+
that already shipped in previous patch releases.
102+
103+
Collecting PRs and changelog entries
104+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105+
106+
For each release, collect merged PRs since the previous release tag.
107+
108+
**Method 1: git log (recommended)**
109+
110+
.. code-block:: bash
111+
112+
# Collect all merge commits from previous tag to stable branch
113+
git log --oneline --merges --first-parent <previous-tag>..stable<XX>
114+
115+
# Example for stable33 since v13.0.0
116+
git log --oneline --merges --first-parent v13.0.0..stable33
117+
118+
# Output format: merge commits with PR references (Merge pull request #XXXX)
119+
120+
To get PR numbers with backport titles directly (faster changelog drafting):
121+
122+
.. code-block:: bash
123+
124+
# Example: from merge commit of previous release to stable branch head
125+
for c in $(git rev-list --reverse --merges --first-parent <release-merge-commit>..stable<XX>); do
126+
pr=$(git show -s --format='%s' "$c" | sed -E 's/^Merge pull request #([0-9]+).*/\1/')
127+
title=$(git show -s --format='%b' "$c" | head -n 1)
128+
printf '%s|%s\n' "$pr" "$title"
129+
done
130+
131+
**Method 2: GitHub CLI (gh)**
132+
133+
.. code-block:: bash
134+
135+
# List merged PRs between two tags/branches
136+
gh pr list -B stable33 -S "merged:>$(git log -1 --format=%ai <previous-tag>)" --json number,title,mergedAt
137+
138+
# Or search for PRs merged after a specific date
139+
gh pr list -B stable33 --state merged --search "merged:>=2025-02-01" --json number,title
140+
141+
To list milestones with current GitHub CLI versions, prefer the API endpoint:
142+
143+
.. code-block:: bash
144+
145+
gh api repos/LibreSign/libresign/milestones?state=all\&per_page=100
146+
147+
**Important: Mapping backports to original PRs**
148+
149+
When collecting PR data for a release, you may encounter backport PRs. These should be mapped to the original PR for proper documentation:
150+
151+
- **Backport PRs** are created with a naming pattern like: ``Backport: fix: ...`` or on a backport branch
152+
- Look at the PR description or linked issues to find the **original PR number**
153+
- In the changelog, use the **backport PR number** (specific to the branch) but reference both
154+
155+
Also exclude PRs that are only part of the release process itself, for example:
156+
157+
- release-drafter alignment or release housekeeping PRs
158+
- follow-up lockfile repair PRs whose only purpose is to fix the backport branch
159+
- hotfix PRs that already generated a published patch release section
160+
161+
Example for handling backports:
162+
163+
- Original PR on main: #6944 "fix: docmdp first signature allow"
164+
- Backport PR on stable33: #6944 (same in this case) or #6945 on stable32
165+
- In changelog, list: ``#6944 fix: docmdp first signature allow`` (use the stable branch specific PR number)
166+
167+
Defining release version numbers
168+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
169+
28170
1. Go to Milestones in the LibreSign repository:
29171

30172
https://github.com/LibreSign/libresign/milestones
@@ -40,13 +182,54 @@ Version numbers
40182
2. To new features, increment with :code:`1` the ``MINOR`` version and reset ``PATCH`` to ``0``.
41183
3. To bug fixes, increment the ``PATCH`` version.
42184

185+
.. note::
186+
187+
The Release Drafter workflow can help by pre-filling the draft version from
188+
the stable branch history, but the final version decision is still validated
189+
during the changelog curation step.
190+
43191
Stable branches
44192
---------------
45193

46194
Each **stable branch** in LibreSign corresponds to a specific Nextcloud **MAJOR** version.
47195

48196
For example: ``stable21`` is compatible with Nextcloud 21.
49197

198+
Changelog format
199+
----------------
200+
201+
The :code:`CHANGELOG.md` file uses a specific format to document releases. Follow this pattern:
202+
203+
.. code-block:: markdown
204+
205+
## [13.0.1] (stable33) - 2025-02-18
206+
### Fixed
207+
- #6944 fix: docmdp first signature allow
208+
- #6945 fix: signature status propfind
209+
- #6940 fix: avoid empty crl engine default
210+
211+
## [12.2.1] (stable32) - 2025-02-18
212+
### Fixed
213+
- #6943 fix: docmdp first signature allow
214+
- #6946 fix: signature status propfind
215+
- #6939 fix: avoid empty crl engine default
216+
217+
**Key format rules:**
218+
219+
- Use semantic versioning: ``[MAJOR.MINOR.PATCH]``
220+
- Include the stable branch in parentheses: ``(stableXX)``
221+
- Add the release date: ``YYYY-MM-DD``
222+
- Group changes by type: ``Added``, ``Changed``, ``Fixed``, ``Removed``, etc.
223+
- List PR number with hash: ``#XXXX`` followed by a colon and description
224+
- Use lowercase for descriptions (following conventional commits)
225+
- For backport releases, use the **stable branch-specific PR number** even if it differs from the original
226+
- Always add new entries at the top (most recent first)
227+
- Prefer user-visible changes in the release notes; keep purely internal test/refactor/dependency entries only when they are relevant to support or compatibility.
228+
- Collapse dependency updates into a single changelog item (e.g. ``Bump dependencies``) instead of listing each maintenance PR.
229+
- Always include ``Update translations`` in the release changelog.
230+
- Do not include Dependabot-only commits in the final changelog section.
231+
- Treat GitHub generated release notes as a draft source only; rewrite the final section so it tells the release story instead of listing every backport PR individually.
232+
50233
Release checklist
51234
-----------------
52235

@@ -87,16 +270,28 @@ with the correct values as you progress through the steps.
87270
- [ ] Go to the main branch, pull the latest changes and create a new branch called `chore/changelog`
88271
- [ ] Add the changelog entries to the `CHANGELOG.md` file, following the pattern used in the file.
89272
- [ ] Make this to all releases that will be done in this process.
273+
- [ ] Assign the PR to the correct milestone
274+
- [ ] `main` uses the current `Next Major (XX)` milestone from `appinfo/info.xml`
275+
- [ ] each stable branch uses its matching `Next Patch (XX)` milestone
90276
- [ ] Create a PR against `main` branch at the `CHANGELOG.md` file with the changelog of all milestones that are subject to the release. Look the pattern used in the file and follow it.
91-
You can use the :code:`[skip ci]` tag in the commit message to skip the CI checks for the backport PRs to make the process faster.
277+
The **last commit** of every release PR must include :code:`[skip ci]`.
278+
This keeps the release train moving and avoids waiting for a full CI cycle
279+
right before the tag and publication steps.
280+
Do not use the release PR to change anything beyond changelog and version bumps.
92281
```
93282
name suggestions to commit and pull request:
94283
chore(release): Changelog for 20.1.9
95284
chore(release): Changelog for 20.1.9 and 20.1.8
96285
```
97286
- [ ] Merge the PR
287+
- [ ] **Version consistency check** (before backporting):
288+
- [ ] Verify :code:`appinfo/info.xml` has the correct version
289+
- [ ] Run: :code:`npm version --no-git-tag-version $(xmllint --xpath '/info/version/text()' appinfo/info.xml)`
290+
- [ ] Verify :code:`package.json` and :code:`package-lock.json` were updated correctly
291+
- [ ] Commit these changes together with the changelog PR if needed
98292
<!-- Duplicate the follow steps for each version that will be released, starting with the oldest version. -->
99293
<!-- Pay attention to start with the **oldest** version here, so the appstore and github releases show the newest version as "Last release" and them. -->
294+
<!-- Do not publish the newer release until the older release workflow is fully finished and validated in the App Store. -->
100295
<!-- Replace "XX" with the Nextcloud stable branch number e.g. "22" for "stable22" -->
101296
<!-- 1. Replace "20.1.9" with the version number e.g. "12.2.4" -->
102297
<!-- Replace "20.1.8" with the previous version number e.g. "12.2.3" -->
@@ -112,14 +307,27 @@ with the correct values as you progress through the steps.
112307
# Make sure the printed version matches the info.xml version
113308
npm version --no-git-tag-version $(xmllint --xpath '/info/version/text()' appinfo/info.xml)
114309
```
310+
- [ ] Make sure the final commit of the PR uses :code:`[skip ci]`
311+
- [ ] Confirm the PR only changes release files: `CHANGELOG.md`, `appinfo/info.xml`, `package.json`, `package-lock.json`
312+
- [ ] Assign the PR to the matching `Next Patch (XX)` milestone of the stable branch
115313
- [ ] Merge the backport
116-
- [ ] Do a quick smoke test signing documents with:
117-
- [ ] Chrome
118-
- [ ] Edge
119-
- [ ] Firefox
120-
- [ ] Safari
314+
- [ ] **Smoke test** - Sign a document in each supported browser:
315+
- [ ] Chrome (latest version)
316+
- [ ] Edge (latest version)
317+
- [ ] Firefox (latest version)
318+
- [ ] Safari (latest version)
319+
- [ ] Verify: Request signing, Add signature, Validate signature in AppStore/File Manager
320+
- [ ] **Final validation checks**:
321+
- [ ] Verify version number in :code:`appinfo/info.xml` matches release tag
322+
- [ ] Verify changelog in :code:`CHANGELOG.md` is correct and properly formatted
323+
- [ ] Check GitHub Actions status for the merged PR
324+
- [ ] Review AppStore entries for the stable branch (if available)
121325
- [ ] Create the new milestone
122326
- [ ] Rename milestone `💚 Next Patch (XX)` to `v20.1.9` in https://github.com/LibreSign/libresign/milestones
327+
- [ ] Confirm the milestone was correctly renamed before writing the release body:
328+
```sh
329+
gh api 'repos/LibreSign/libresign/milestones?state=open' --jq '.[] | "\(.number) \(.title)"'
330+
```
123331
Unless last release of the stable branch:
124332
- [ ] Create a follow up milestone for `💚 Next Patch (XX)` (Due date in ~4 weeks, ~4 days for beta/RC)
125333
- [ ] Move all open issuesfrom milestone `v20.1.9` to `💚 Next Patch (XX)`: https://github.com/LibreSign/libresign/issues?q=is%3Aissue%20state%3Aopen%20milestone%3Av20.1.9
@@ -128,9 +336,14 @@ with the correct values as you progress through the steps.
128336
- [ ] Archive all issues and PRs that were merged in this release
129337
- [ ] https://github.com/orgs/LibreSign/projects/2/views/4
130338
- [ ] Create a new release
339+
- [ ] Confirm the exact commit that will be tagged is the current head of the stable branch:
340+
```sh
341+
git ls-remote origin refs/heads/stable20 | awk '{print $1}'
342+
```
131343
- [ ] Prepare a (pre-)release in https://github.com/LibreSign/libresign/releases/new?tag=v20.1.9&target=stable20
132344
- [ ] Make sure that chosen tag is v20.1.9, target is stable20, and previous tag is v20.1.8
133345
- [ ] Add the content of respective `CHANGELOG.md` section from merged PR
346+
- [ ] In the release body, use the final closed milestone name `v20.1.9` after the milestone rename, never the previous `Next Patch (XX)` name
134347
- [ ] Use the **Generate release notes** button and wrap the output result into
135348
```
136349
## What's Changed
@@ -141,4 +354,15 @@ with the correct values as you progress through the steps.
141354
- [ ] Publish release
142355
- [ ] Check that the GitHub Action started: https://github.com/LibreSign/libresign/actions
143356
- [ ] Ensure that the GitHub Action finished successfully: https://github.com/LibreSign/libresign/actions
357+
- [ ] **Post-release validation**:
358+
- [ ] Verify the new version appears in AppStore: https://apps.nextcloud.com/apps/libresign
359+
- [ ] Check that the package was properly built and published
360+
- [ ] Verify changelog is visible on GitHub Releases page
361+
- [ ] Confirm no errors in GitHub Actions logs
362+
- [ ] If a publication fix is merged after the release tag is created, do not only rerun the old workflow
363+
- [ ] Delete the GitHub release and the tag
364+
- [ ] Recreate the tag from the updated stable branch head
365+
- [ ] Recreate the GitHub release so the workflow checks out the corrected commit
366+
- [ ] If there is another release to publish in the same cycle, stop here and wait for all checks above to be green before creating the next release tag
367+
- [ ] Only after the older release is visible and correct on https://apps.nextcloud.com/apps/libresign/, publish the next newer release
144368
- [ ] Post the changelog in [💬 LibreSign team public 👥](https://t.me/LibreSign)

0 commit comments

Comments
 (0)