We like release notes at Redgate. In one glance, readers should be able to see the number of the release, the date it was released, what the latest features are, any additional improvements, fixes that have been accomplished, and any known issues.
It’s easier than it sounds and all release notes follow this general structure:
0.0.0 - Date
- Write the new features as bullet points like this.
- List them approximately in order of importance. If there’s one major new feature, put it before smaller ones.
- Link to relevant documentation where appropriate (eg, a page describing the feature in more detail).
- If a feature involves changes to the UI, consider including a screenshot.
- If there are improvements to current features, list those as well.
- Use a bullet point list again.
- And embolden the things users will interact with.
- Use terms such as now and no longer to clarify you're describing how the tool behaves in this release. Otherwise, it may sound as if you're describing the bug, not the fix. For example, don't write Materialized views script hidden fields, as it’s not clear if that’s what used to happen, or what happens now. Instead, describe what the fix has changed. For example, write, Materialized views no longer script hidden fields, or Materialized views now script hidden fields, depending on what’s changed.
- If the bug has a JIRA reference (eg, SB-5415), include it at the start of each bullet point, followed by a colon. If the same issue has multiple bug codes, include them all in the same bullet point.
- List the fixes in numerical order according to the bug code.
- If the fixes have relevant documentation, link to it.
- If the release introduces new issues or bugs, list them.
- If the issues have bug numbers, include them.
- Link to any relevant resources.
A good example is SQL Source Control 5.0. Note the product name isn’t required at the top of the release notes, because the reader is already on the SQL Source Control release notes page.
5.0.0 - May 23rd, 2016
Improved migrations solution
Migration scripts in SQL Source Control 5 now support:
- Git and working folder, along with every other version control system
- Branching and merging, conflict resolution, and interactive rebasing version control features
- Data-only migration scripts. These are scripts that aren’t linked to specific schema changes
- Also, SQL Source Control no longer needs a dedicated migration scripts repository
- Redesigned Commit and Get latest tabs
- Improved Refresh performance
- Support for SQL Server Management Studio 2016
- Ability to switch to other Redgate tools by clicking the product logo in the top-left corner
- Objects not covered by a migration script can now be excluded from a get latest
- SQL Source Control no longer throws errors on machines with FIPS enabled
- SOC-7840: SQL Source Control no longer throws an error message when switching databases during an SVN commit
- SOC-7346: SQL Source Control no longer throws an error message when performing two operations on the same database linked to SVN
- SOC-7693: SQL Source Control no longer throws an error message when performing two operations on the same database linked to Git
- SOC-7504: SQL Source Control no longer throws a DmvResultMergeException
- SOC-7834: Fix support for Team Explorer 2012 in SSMS 2008/2008R2
- SOC-7554: SQL Source Control no longer errors intermittently on refresh
Also note that not every heading needs to be included if it’s not necessary. There were no known issues in the release of SQL Source Control 5.0.0, so none needed to be listed.