summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/how/documentation/release_notes.mdwn
blob: 980ce9d874d14b297d363db9cabb609d086890d2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
[[!meta title="Checklist for release notes"]]

  - 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 a release candidate was announced, read the call for testing
    - Analyze the changes already made on the website and link to them:
      - in testing for a major release: `git diff origin/master...origin/testing wiki/src/**/*.{mdwn,html}`
      - in stable for a minor release: `git diff origin/master...origin/stable wiki/src/**/*.{mdwn,html}`
    - 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 minor 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-bundle.git/tree/Bundle-Data/Docs/ChangeLog.txt?h=maint-7.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>
    - Add [[screenshots|contribute/how/documentation/guidelines#screenshot]] 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. ([[!tails_ticket #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.
    - Make sure there's an `announce` tag to have an email sent to the
      news mailing list.
  - Update the [[support/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.