• Create a branch based on the development branch for this release
  • web/nnnnn-x.y-release-notes
  • Copy template from contribute/how/documentation/release_notes/template.mdwn to news/version_x.y.mdwn
  • Replace placeholders in template
• Gather information about changes
  • Tails changelog
    • https://git-tails.immerda.ch/tails/tree/debian/changelog?h=stable
    • https://git-tails.immerda.ch/tails/tree/debian/changelog?h=testing
      • If the changelog of the final release has not been written yet, either book some time to update the release notes on the day of the release or go through the tickets marked as "Ready for QA" and "Fix committed" on Redmine.
  • If a release candidate was announced, read the call for testing
  • Analyze the diff of packages
    • in testing for a major release: wget http://nightly.tails.boum.org/build_Tails_ISO_testing/lastSuccessful/archive/latest.iso.packages
    • in stable for a bugfix release: wget http://nightly.tails.boum.org/build_Tails_ISO_stable/lastSuccessful/archive/latest.iso.packages
    • diff -u ~/Persistent/master/wiki/src/torrents/files/tails-amd64-*.packages latest.iso.packages | wdiff --diff-input --terminal --auto-pager
  • If an important application was updated to a new upstream release, read its Changelog to find relevant highlights:
    • Tor: https://blog.torproject.org/
    • Tor: https://gitweb.torproject.org/tor.git/tree/ChangeLog
    • Tor Browser: https://gitweb.torproject.org/builders/tor-browser-build.git/tree/projects/tor-browser/Bundle-Data/Docs/ChangeLog.txt?h=maint-8.0
    • Firefox: https://www.mozilla.org/en-US/firefox/52.0/releasenotes/
    • Thunderbird: https://www.mozilla.org/en-US/thunderbird/notes/
    • Electrum: https://github.com/spesmilo/electrum/blob/master/RELEASE-NOTES
    • TorBirdy: https://gitweb.torproject.org/torbirdy.git/tree/ChangeLog
    • obfs4proxy: https://anonscm.debian.org/cgit/pkg-privacy/packages/obfs4proxy.git/tree/ChangeLog
    • Enigmail: https://enigmail.net/index.php/en/download/changelog
    • VirtualBox: https://www.virtualbox.org/wiki/Changelog
  • Add screenshots of
    • Cool stuff, to show off!
    • Known issues, if that makes them easier to understand.
  • Document manual steps that persistence users may need to go through, taking into account that we support automatic updates from the two last releases (not mentioning manual updates). It may imply to refer to, or copy from, such instructions that were documented in the previous release notes.
• Write the draft
  • As a rule of thumb, get inspiration from all these data sources but write new sentences yourself. Changelog and release notes are written for different audiences and for different purposes.
  • Focus on what is the benefit for the user (if any, if relevant, and not to wordy).
    • For example: Automatically save the database of KeePassX after every change to prevent data loss when shutting down.
  • Our release notes should satisfy a diverse audience of both very technical and less technical users. As such, it's all-right to include more technical language, for example for security benefits that are not visible, as long as:
    • Changes that are noticable by less technical users are still understandable by them.
    • What we are describing in non-technical language is understandable by more technical users.
    • We point to more technical sources like tickets and design documents.
    • Technical items are less proheminent.
    • For example: Harden our firewall by rejecting RELATED packets and restricting Tor to only send NEW TCP syn packets. (#11391)
  • Use full sentences for major changes ("We installed", "You can")
  • Use present tense without subject for minor changes ("Upgrade", "Fix")
  • Mention updates as "Update Xyz to [1.2.4]."
    • Mention previous version if we skipped some "Update Xyz from 1.0.0 to [1.2.3]."
    • Link to release notes if any, or changelog
    • For Linux upgrades add "This should improve the support for newer hardware (graphics, Wi-Fi, etc.)"
  • Order items to put the most visible, less technical, and most popular items first while not being afraid of putting more technical items as well down the list.
  • Document known issues
  • Update the meta title directive.
  • Update the meta date directive.
• Update the known issues page:
  • Add regressions brought by the new release.
  • Remove older known issues that are fixed by the new release.
• Format
  • Link to ticket for fixed problems and changes that are well justified in Redmine
  • Put the period before ticket number
    • "Bla bla. ([!tails_ticket 1234])"
• Prepare a tweet with highlights:
  • Tails x.y is out: https://tails.boum.org/news/version_x.y, bla bla bla, and more.
  • Add it as a comment to the ticket for the release notes.