Bugzilla Release Noting Guide

The following is a guide for anyone who needs to work on the release
notes of Bugzilla which appear at docs/rel_notes.txt.

Release notes can be inserted as a part of a patch, especially if you
are willing to follow the appropriate style. The person responsible for
the release notes may end up changing what you wrote.

Typically however people are forgetful, so release notes are updated by
the release noter towards the end of the development cycle. The release
noter will attempt to discover what has been forgotten.

If you are not the release noter, to ensure things are release noted it
is generally easier to comment on the release notes bug for this
development version (search for "release notes") than create actual patches.

General Style Issues

Please attempt to follow the existing style of the release notes.
In particular, this means:

Please use the same heading style and heading titles for new
sections and subsections.

Please use the same style for indicating bug numbers.

Please use the same style for differentiating separate issues.

Updating Release Notes Before Release

The following gives a list of tasks that should be performed on
the release notes before release:

Update the introduction.

Update the dependencies section with any new dependencies.

Determine if any new deprecations have to be added.

Determine if the existing deprecations are now enforced and
can therefore be removed.

Determine if there have been any new important outstanding issues
discovered.

Determine if there are any previously outstanding issues fixed in
this version, if so, move them to one of the subsections for this
version.

Using a combination of Bonsai and Bugzilla, ensure all the
subsections contain all significant issues. Do not include all
issues or you will make the release notes too cluttered to be
useful. All security issues go in the "Security Issues" section.
Otherwise, if the administrator may need to know the issue, put it in
the "Important Changes" section. Otherwise, if it is a bug fix, put it
in the "Bug fixes" section. Otherwise, put it in the "Other Changes"
section.

If there are new software requirements, add an entry into
"Important Changes" documenting them, and similarly another
entry for version requirement changes.

Release notes for previous versions are not kept for historical
value, they are kept for administrators who are jumping over
versions of Bugzilla. Hence, search the previous versions' notes
and determine if any notes are no longer relevant and delete any
that aren't.

Search bugs fixed during this development version for the text
"release note", and see if there is anything that needs to be
done indicated on any of these bugs.

Ensure you have taken into account all comments on the release
notes "bug" for this development version.

Double check all your bug numbers.

Updating Release Notes After Release

Once you have released, there are a few tasks you should do to
prepare for the development version:

Create new sections for the next stable release that is being
developed. Create a new major section, and new subsections,
"Security Issues", "Important Changes", "Other Changes", and
"Bug Fixes".

Eliminate the introduction for the previous version, and insert
text saying something like:

2.108 has not been released yet - these are prerelease notes.
Insert nice little intro for version 2.108 here.

Stable Point Releases

Stable point releases are generally done on branches, and hence their
release notes can fork from those on the trunk.

However, administrators often jump from stable point releases up
to the next stable major release, so you need the trunk to indicate
what has changed since the point releases.

Hence, please ensure that the release notes are brought from the branch
to the trunk. You should place the section for that version before the one
for the current development version.

Furthermore, check that there aren't existing notes in the development
version section that instead apply to the stable point release section. If
so, move them there. If there is an similar note already in the stable point
release section, consolidate them there.