Releases:Release Notes System
How to (draft and structure and combine and) create release notes for a new version of Camino
by Smokey Ardisson
Camino uses three basic styles of release notes: the Milestone style, the Final Release style, and the Security and Stability Update style. Each of these styles varies slightly in format, structure, and language. This document explains the system finalized during the 1.1/1.5 release cycle and updated with improved language in the 2.0 cycle.
When the Final Release and Security and Stability Update notes appear on the website, there are slight layout changes involved, but the format and structure remain essentially the same. A fourth, website-only, style is the “Complete Release Notes”, which consists of all the Milestone notes for a given release plus any relnote-worthy changes between the last Milestone and the Final Release, in a slightly different format (this supplements the normal Final Release style notes for a version by providing a comprehensive changelog-style notes).
Since the specifics of the "standard text" will change over time, be sure to consult the relevant prior release for the latest wording.
The first style is the Milestone style, used for alpha and beta milestones. This style is the most informal and consists largely of a component-ordered list of changes since the last final release or milestone. These changes are drawn from the respective Releases:N.n:Notes pages, which in turn are “branched” from the “running release notes” page for the release, Releases:Release Notes N.n. The wiki pages list all “relnote-worthy” changes since the last final release (or the last milestone). To be “relnote-worthy,” a checkin typically has to be a user-facing feature addition, behavior change, or bug fix. Fixes for regressions that shipped in earlier milestones are “relnote-worthy,” but fixes for regressions introduced in the current milestone cycle are not.
The Milestone style consists of 3 major sections, “About Camino® N.n Milestone” (with the ®), “Features in Camino N.n Milestone” (without the ®), and “Known Issues”. A new Features section is prepended for each subsequent milestone, e.g., Camino 1.1a1 will have one Features section, but Camino 1.1b might have 3, one for the 1.1a1, 1.1a2, and the topmost Features section for 1.1b.
About Camino® N.n Milestone
This section (H1) contains a paragraph highlighting the main areas of change since the previous Final Release, a paragraph of caution tailored to the Alpha or Beta (with slightly different wording for alpha vs. beta), a single sentence paragraph about Firefox/Gecko compatibility, and, where necessary, a final paragraph directing users of a no-longer-supported OS version to the last Security and Stability Update version for their OS.
In each subsequent milestone, be sure to increment the "nth preview release" text in the first sentence.
Features in Camino N.n Milestone
List, by functional area (H2). Don't include functional areas which have no checkins. Keep the list of functional areas consistent within a release cycle.
The H1 for this section is followed by an explanatory sentence, where the "since the last release" phrase reflects either the last final release or the last milestone, e.g. for Camino 2.0 Alpha 1 the sentence is “The following changes and improvements have been made since the Camino 1.6 release.” but for Camino 2.0 Beta 1 the sentence is “The following changes and improvements have been made since the Camino 2.0 Alpha 1 release.”
Header (H1) followed by a list. Updated with each subsequent milestone. Try to prune all but most serious carry-over notes from previous release. What qualifies a bug to be a known issue? Major, often not ours, common problem.
Note that lazy journalists use this section to come up with "bugs in Camino" so try to differentiate between issues that are "ours" and are regressions and those that are caused by third-party software (and are often on-going, not regressions).
Final Release style
The second style is the Final Release style, used for for the first release of a new Camino version. This style is more formal and consists largely of a summary of significant new features or changes since the last final release. These changes are drawn from the respective Releases:N.n:Notes pages used for the milestone releases and the last “running release notes” page for the release, Releases:Release Notes N.n.
The Final Release style consists of 3 major sections, “About Camino® N.n” (with the ®), “Features in Camino N.n” (without the ®), and “Known Issues”.
About Camino® N.n
This section contains a paragraph introducing the release, including a single sentence about Firefox/Gecko compatibility, a single-sentence paragraph noting that these are only some of the changes, and, where necessary, a final paragraph directing users of a no-longer-supported OS version to the last Security and Stability Update version for their OS (or to upgrade to the final point release of their major Mac OS X version).
Features in Camino N.n
The Features section consists of an introductory sentence containing a link to the "complete" changelog-style notes, followed by about a dozen short, descriptive headings (bold, but as first-level list items), each with list items below providing more detailed descriptions of the elements of the feature.
However, on the website, the headings are H3s and the detailed descriptions are P elements.
List based on the Known Issues of the milestone releases. Try to prune all but most serious carry-over notes from previous release. What qualifies a bug to be a known issue? Major, often not ours, common problem. Note that lazy journalists use this section to come up with "bugs in Camino" so try to differentiate between issues that are "ours" and are regressions and those that are caused by third-party software (and are often on-going, not regressions).
In the Final Release and Security and Stability Update styles, the header is followed by a sentence pointing users to the Help page.
This example is from 1.6; update to reflect changes introduced in 2.0
Security and Stability Update style
This style basically replaces the About section of the Final Release and appends a set of lists for each subsequent security and stability release under the “Changes since Camino N.n” header. This style also updates the Known Issues, if applicable. Try to keep any changes light (repeat same list item texts each security release, where possible) for l10n.
About Camino® N.n.n
In the Release Notes RTF files, the entire About section is replaced with an introductory sentence (see below), which can take three different forms over the course of the branch's lifetime: first branch release, second and subsequent branch release, and the final branch release when it EOLs support for a major version of Mac OS X (note that we did not use this EOL style for 1.5.5, which only dropped support for old versions of 10.3, not 10.3.9).
N.B In the Release Notes on the website, the introductory sentence appears right under the "Camino N.n.n Release Notes" H2. Then comes the “Changes since Camino N.n” section (see below), and then comes the original “About Camino® N.n” section, minus the first "After a year of hard work" paragraph.
First branch release
Second and subsequent branch release
Branch EOL Release
Changes since Camino N.n
This section lists changes in each security and stability update. Below the section header is an explanatory sentence (the version numbers never change in the header and the explanatory sentence).
Following those items, there is a subhead (just bold text in the RTF), “Camino N.n.n contains the following improvements over version N.n.n-1:” (both of these version numbers do change with each security release, of course) and a lists of changes. Newer security releases appear above/before older releases.
As in Final Release style, this is a list, updated as needed. Try not to modify these, but when necessary to do so, be sure to 1) alert l10n and 2) post the updated Known Issues on the release's release notes web page.
It's great to be able to delete a known issue during a branch cycle, but it's less fun to have to add an issue or modify the text of one.