mirror
/
sane-project-backends
kopia lustrzana https://gitlab.com/sane-project/backends
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

doc: Update the releasing documentation

release-1.1.x
Povilas Kanapickas 2022-01-18 22:12:19 +02:00
rodzic 3738eb9e42
commit bb0bee92f6
1 zmienionych plików z 44 dodań i 65 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

109
doc/releases.md
Wyświetl plik

@ -24,14 +24,9 @@ Once you pick a date (and time), say `DT`, the planning is simply a
matter of counting back from there: matter of counting back from there:
- `$DT - 0 days`: **release** :confetti_ball: - `$DT - 0 days`: **release** :confetti_ball:
- `$DT - 7 days`: **code freeze** after which only documentation - `$DT - 21 days`: **branch off** after which the release branch will not get any new features,
changes are allowed. As an exception, critical issues, such as only bug fixes and translations.
hardware destroying bugs, compile errors and completely unusable - `$DT - 35 days`: **schedule announcement** including the timetable.
backends, may still be addressed.
- `$DT - 21 days`: **feature freeze** after which only bug fixes and
documentation changes are allowed.
- `$DT - 35 days`: **schedule announcement** including the timetable
and a pointer to the corresponding GitLab milestone.
Feel free to adjust the offsets if that works better. Also, pinging Feel free to adjust the offsets if that works better. Also, pinging
on the mailing list well in advance, say two, three months, about a on the mailing list well in advance, say two, three months, about a
@ -45,30 +40,23 @@ suitable date for everyone involved is a good idea.
## Schedule Announcement ## Schedule Announcement
Create a milestone on GitLab that shows the schedule. The milestone Send an announcement to the `sane-devel` mailing list announcing the schedule.
can be used to collect issues resolved and merge request merged to
`master` that will be included in the `$new_version` and coordinate
work leading up to the release.
Send an announcement to the `sane-devel` mailing list announcing the All notable changes are tracked as separate files in the newsfragments directory which means there's
schedule and point to the milestone. no need to track them manually.
Add closed issues that triggered code changes and merge requests to ## Branch off
the milestone so you get an idea of what has been added, fixed,
changed or removed. This will serve as the input for the NEWS file,
together with `git log` and `git diff` outputs.
## Feature Freeze A separate branch for the upcoming release is created on the repository. This marks the point when
the code for the release effectively enters a feature freeze and no new features will land into
the release branch.
New backends, support for new models and new bells and whistles for Use branch in the format of `release-1.2.x` so that it's clear that further bugfix releases will
existing backends (and frontends) are no longer allowed so this is a happen on that branch.
good time to cut a `release/$new_version` branch from the latest
public `master` and publish it on GitLab.
Notify `sane-devel` of the Feature Freeze and point out that merge Notify `sane-devel` of the Branch Off and point out that merge requests that have to be included
requests that have to be included in the upcoming release need to be in the upcoming release need to be targeted at release branch. Anything else can go to `master` as
targeted at `release/$new_version`. Anything else can go to `master` usual.
as usual.
For backends added since the `$old_version`, make sure that its For backends added since the `$old_version`, make sure that its
`.desc` file includes a `:new :yes` near the top. You can find such `.desc` file includes a `:new :yes` near the top. You can find such
@ -81,52 +69,46 @@ git ls-files -- backend | while read f; do
done | cat done | cat
``` ```
## Code Freeze Feature changes are no longer allowed, bar exceptional circumstances, so now is a good time to
sync the `po/*.po` files in the repository for translators.
Code changes are no longer allowed, bar exceptional circumstances, so Announce the Branch Off on `sane-devel` and invite translators to contribute their updates.
now is a good time to sync the `po/*.po` files in the repository for Release manager should ensure that whichever branch the translator work on, their work lands on
translators. both the release branch and the master branch.
Announce the Code Freeze on `sane-devel` and invite translators to
contribute their updates.
Start creating the `NEWS` file section for the `$new_version`. You
should now have a list of issues and merge requests to help you get
started. The following commands may be helpful as well
``` sh
git diff --stat $old_version..release/$new_version | sort -k3 -n
# sorted list of heavily modified files
git log $old_version..release/$new_version
git diff $old_version..release/$new_version # nitty-gritty details
```
> Note that `po/*.po` files normally see quite a lot of changes due to
> the inclusion of source code line numbers.
Occasionally, you may notice changes that have not been documented, Occasionally, you may notice changes that have not been documented,
either in a `.desc` file or a manual page. Now is a good time to either in a `.desc` file or a manual page. Now is a good time to
rectify the omission. rectify the omission.
Happy that `NEWS` covers everything? Then The `NEWS` file is updated during the release time, there's no need to do anything with the
release notes now.
``` sh
git commit NEWS
git push origin release/$new_version
```
on the day of the release.
## Release ## Release
Once `release/$new_version` contains everything that should go in, The release consists of two parts: a release notes MR and the actual release.
including the changes to the `NEWS` file, releasing `sane-backends` is
as easy as pushing a tag and clicking a web UI button. GitLab CI/CD The release notes are handled by the towncrier tool. The easiest way to use it is from virtualenv:
``` sh
virtualenv some/path/to/virtualenv
source some/path/to/virtualenv
pip install towncrier
```
To update the `NEWS `document, run the following:
```
towncrier --version $new_version --date `date -u +%F`
```
After that, create a new MR, merge it and fetch the new release branch.
The actual release is as easy as pushing a tag and clicking a web UI button. GitLab CI/CD
takes care of the rest. takes care of the rest.
``` sh ``` sh
git tag -a -s $new_version -m Release git tag -a -s $new_version -m "Release $new_version"
git push --tags origin release/$new_release git push --tags origin release-$new_release
``` ```
The final job in the release pipeline that is triggered by the above The final job in the release pipeline that is triggered by the above
@ -209,12 +191,9 @@ your post approved sooner rather than later.
## Post-Release ## Post-Release
With the release all done, there are still a few finishing touches that need taking care of* With the release all done, there are still a few finishing touches that need taking care of:
* merge `release/$new_version` to current `master`
* remove the `:new` tag from all `doc/descriptions*/*.desc` files * remove the `:new` tag from all `doc/descriptions*/*.desc` files
* add a new `UNRELEASED` section at top of the `NEWS` file
* update this file! * update this file!
* and get those changes on the `master` branch
That's All Folks! That's All Folks!