Publication and working guide for Debian codename version releases
These pages describe in detail the steps required for a successful Debian codename release. One may find similar/additional information in the Teams/Publicity/ReleasePointAnnouncements documentation, however that documentation focuses on point releases (e.g. 12.1 point release announcement) and while most of the instruction here is similar, codename /version releases are very different hence this separate and specific guideline.
Specialized Access
The majority of the steps detailed here require membership in both the Publicity and Webmaster teams as the tasks ahead necessitate work and access across multiple areas and various infrastructure machines, generally this role is held by Press team delegates.
Preparation
A week or so before the release the Release team will reach out to the Publicity team asking for an Announcement draft to be written. We do have a template (needs updating) that can be used and while we strive for consistency in the formatting and presentation of the announcement, one need not be rigid when writing it.
Prepare the draft in the publicity announcements salsa repository. The 1st draft is generally written in English and placed in the announcements/en/drafts location. Try to keep the announcement subject as relevant to the topic at hand. version-release.wml makes the work easier to find, remember everyone will follow that naming standard.
Our announcement takes heavily from the draft working copy that the Release team is working on which can be found in the release-notes folder of the Debian Documentation Project. Be mindful that their draft wording may change or sections removed or added. It would be wise to have a daily check in with the Release team as they can let you know if items have been added or sometimes where to find additional information to present in the announcement.
Despite the notice given, some teams have not had the time or sometimes the inclination to forward blurbs to the Release team, if there is time it is helpful to ping a team or two to ask them to submit information, or you can query the team(s) yourself and add it to the announcement, be mindful with that approach as the information should be present in both the release notes and the announcement.
Validation
When the draft is near completion (90% is a good measure point) send an email to debian-publicity@lists.debian.org, with a CC to debian-i18n@lists.debian.org. The email should ask for content review and translation of the draft, it should also clearly state the planned date for the announcement to go out and at which point the edit window closes so that no further items will be added to the draft, this gives the translators a guideline of when they know the announcement draft is "frozen" and they can begin their final versions of the translation.
Generally within a few hours of the ask, other team members and contributors will proof read the announcement, a bit later the translators will translate the announcement into various languages.
Pay attention to the publicity commits emails (if you are subscribed to them) or IRC notifications so that you are aware of when changes have been made or when a translation has been done. You will need to remember the translation copies later when we prepare the announcement to go live. Translation copies will be found in the same announcements repository inside of the language folder for that language (e.g. publicity/announcements/$lang/drafts/version-release.wml).
Another easier approach, if you are one to ignore git pull information, is on your local copy run: $find -name "codename" from the top level of the announcements directory, this will show each language folder that contains a draft.
Now is an ideal time to ask someone from the Release team to review the original publicity English announcement, be mindful they may be extremely busy, but a second set of eyes on the announcement source from that teams work is always ideal.
Some pitfalls to be aware of when writing the draft announcement:
- Be mindful of links in the documentation, be sure to test each of them.
Take advantage of links that point back to Debian infrastructure, one does not need to be write out: www.debian.org/releases/resource, instead express it as: $HOME/releases/resource.
- Review the links in the draft announcement translations as well. Authors tend to read from the release notes that are most relevant to them as they can read the notes, prepare their own upgrade plans and write about that documentation at the very same time. Sometimes across translations links will point to a different arch or point to the English version of the requested resource.
- Re-read the draft version of the release notes often to see if any changes have been made or a point of clarification was made for users understanding, apply those changes to your draft as needed but not after the 90% mark or after the draft has been sent to the lists as the reviewers and translators may not have time to re-dress the work.
And now the other heavier work begins:
Website preparation
Commit the announcement and translations
As the deadline/release date approaches copy the draft announcement from the announcement draft area to the Debian website repository: webwml/english/News/$year/$yymmdd.wml. Leave the draft in place in the announcement repository as we can review it later for historical reference.
$ cp publicity/announce/en/drafts/codename-release.wml webwml/english/News/$year/$yymmdd.wml $ git add webwml/english/News/$year/$yymmdd.wml $ git commit -m "Debian $XX release announcement" $yymmdd.wml $ git push
Pay close attention to the commit acceptance, you will need the commit hash the system gives you to validate the work of the translators who each have different commit hashes. To unify all of the announcement versions across languages they must all share the same commit hash so that they will all appear on the website in the presented language.
If you missed the hash, you can pull the git log:
$ git log -n 1
or
$ git log -n 1 origin/master
The response will read as such:
$ git log -n 1 origin/master commit 6df41fa490a0238fb83f6832c82f6020a65f4a4a (HEAD -> master, origin/master, origin/HEAD) Author: Donald Norwood <donald@debian.org> Date: Sat Jun 10 12:42:42 2023 -0400
At this point you will edit each of the translations to replace the commit hash inside of their work.
For example when we copy the French translation from publicity/announcements/fr/drafts/codename-release.wml to webwml/en/NEWS/$YYYY/$YYYYMMDD.wml, we will replace the commit hash in the translated file.
Taking from the above example with a commit hash of 6df41 ...
Original
<define-tag pagetitle>Publication de Debian 12 <q>Bookworm</q></define-tag> <define-tag release_date>2023-06-10</define-tag> #use wml::debian::news #use wml::debian::translation-check translation="5e952a33ef16a6a69c339dc8b42c5ff146d447e9" maintainer="Jean-Pierre Giraud"
We will remove the 5e952a... hash and replace it with the hash from the original commit.
Modified
<define-tag pagetitle>Publication de Debian 12 <q>Bookworm</q></define-tag> <define-tag release_date>2023-06-10</define-tag> #use wml::debian::news #use wml::debian::translation-check translation="6df41fa490a0238fb83f6832c82f6020a65f4a4a" maintainer="Jean-Pierre Giraud"
Remember to do this for each translation.