Releases:Release Notes System
How to (draft and structure and combine and) create release notes for a new version of Camino
by Smokey Ardisson
on 2007-08-15
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.
Milestone style
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.
Alpha text
Beta text
About Camino® 2.0 Beta 1
Camino 2.0 Beta 1 is the second preview release of a significant upgrade to the popular Mac OS X browser using Mozilla.org’s Gecko HTML rendering engine. Notable improvements include rearranging tabs by drag and drop, the ability to disable “Block Flash animations” on a per-site basis, tab overview, full content zoom, better support for Full Keyboard Access in the browser window, and a “Recently Closed Pages” menu.
Note that Camino 2.0 Beta 1 is in the “beta” stage, which means that it is close to its final shipping state. We feel that it is usable on a day-to-day basis and a large improvement over Camino 1.6, but you may still experience issues and some functionality may not work entirely as intended. The goal of this early release is to demonstrate the team’s progress and to allow users to report problems before the final release.
Camino 2.0 Beta 1 shares the same code base as Firefox 3.0, both being based on version 1.9.0 of Gecko, and thus shares many of the security fixes and Gecko improvements that are in that version of Firefox.
Camino 2.0 Beta 1 is available for Mac OS X 10.4 and later.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.”
Features in Camino 2.0 Alpha 1
The following changes and improvements have been made since the Camino 1.6 release.
Privacy & Security
- Camino now displays error pages for secure web pages using invalid or untrusted certificates.
- Camino now supports adding exceptions to allow access to secure web pages whose certificates are invalid or untrusted.
Known Issues
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).
Known Issues
- Delete no longer functions as a keyboard shortcut for Back.
- Scroll bars will appear active at all times.
- If “Ask me before accepting each cookie” is checked, Camino will display a cookie dialog for each cookie request from a web page.
- Camino no longer supports Shockwave Player 10 and older; to display Shockwave content, install Shockwave Player 11 or newer.
- Version 2.2 of the Flip4Mac (F4M) plug-in for displaying Windows Media content causes major rendering issues in Camino. The Flip4Mac team has fixed this problem in version 2.2.1.11 of the plug-in.
- After visiting enough pages with Flash content while browsing, Camino may stop functioning correctly. Quitting and re-launching Camino will resolve the problem. This behavior is caused by a bug in the Flash plug-in and is fixed in version 10.0 of the plug-in.
- Some versions of the third-party add-on 1Password are not compatible with Camino. These versions can cause Camino to crash on launch, hang when importing bookmarks, and hang when pasting into the location bar. Make sure that you are running the latest version of 1Password, and if you continue to experience issues, disable 1Password’s integration with Camino and contact 1Password support.
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).
About Camino® 1.6
After nearly a year of hard work by devoted volunteers, the Camino Project is proud to give you Camino 1.6. This latest version includes many bug fixes and new features, providing all users with an improved browsing experience. Like Camino 1.5, this release displays web pages with Gecko 1.8.1, the same rendering engine used by the popular Firefox 2 web browser, and thus shares many of the security fixes and Gecko improvements that are in that version of Firefox.
The features listed below are just some of the many changes in Camino 1.6.
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.
Features in Camino 1.6
The following are the major changes and improvements made since the Camino 1.5 release. A full list is available on our website.
- Improved toolbar search
- The search field in the toolbar now includes a simple editor that allows deleting, renaming, and reordering search engines.
- Camino now supports OpenSearch search engine plug-ins. New search engines can be added to the toolbar’s search field by automatic discovery or by web pages that provide links to OpenSearch plug-ins.
Known Issues
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.
Known Issues
For information about other issues or problems, please visit our Help page.
- Version 2.2 of the Flip4Mac (F4M) plug-in for displaying Windows Media content causes major rendering issues in Camino. The Flip4Mac team will fix this problem in a future release of the plug-in.
- After visiting enough pages with Flash content while browsing, Camino may stop functioning correctly. Quitting and re-launching Camino will resolve the problem. This behavior is caused by a bug in the Flash plug-in, which will be fixed in a future Flash plug-in release.
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
About Camino® 1.6.1
Camino 1.6.1 is a security and stability update for Camino 1.6. All users are urged to upgrade.Second and subsequent branch release
About Camino® 1.6.2
Camino 1.6.2 is a security and stability update for Camino 1.6.x. All users are urged to upgrade.Branch EOL Release
About Camino® 1.6.10
Camino 1.0.5 is a security and stability update for Camino 1.0.x users running Mac OS X 10.2.8. Camino 1.0.5 will be the last update in the 1.0.x series and is thus the last version of Camino to support Mac OS X 10.2.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.
Changes since Camino 1.6
The following changes and improvements have been made since the Camino 1.6 release.
Camino 1.6.1 contains the following improvements over version 1.6:
- Camino will no longer crash when attempting to add a search engine that uses POST.
- Camino displays more useful error messages when it is unable to add a search engine.
- Camino supports a wider variety of search engine definition files.
- Restored compatibility with Adobe Dreamweaver and other applications that use a deprecated AppleEvent to open documents in Camino.
- Improved robustness of code used to access the Keychain.
- Command-period will now close the Find toolbar on Mac OS X 10.5.
Known Issues
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.
