The new release notes infrastructure has been merged into the develop branch.
The process is fairly simple: if you're making a user/admin facing change for 1.0, it must be captured in a reStructuredText file under "documentation/whats-new/release-1.0/". Any affected patch won't make it through code review until the release note is present.
Providing technical release notes for "under the hood" stuff (like replacing SimpleXMLRpcServer on the lab controllers with gevent+flask) is encouraged, but not required.
The exact formatting and wording of the draft notes isn't a big deal, the main requirement during development is to make sure that the gist of any changes is captured in that directory, so that we don't forget to mention it when preparing the final version of the notes. Using separate files rather than all updating a single file should help to avoid spurious merge conflicts on Gerrit.
Once we hit feature freeze in early March, I'll take care of reformatting the notes with an eye to making them more readable (splitting them out into admin/user/developer notes, grouping notes for related features together, etc).
For reference, basic instructions are kept as a comment in: http://git.beaker-project.org/cgit/beaker/tree/documentation/whats-new/index...
Cheers, Nick.
First let me say, thank you Nick for setting this up, user-facing release notes have been sorely lacking.
Excerpts from Nick Coghlan's message of 2013-02-13 15:28:31 +1000:
The process is fairly simple: if you're making a user/admin facing change for 1.0, it must be captured in a reStructuredText file under "documentation/whats-new/release-1.0/". Any affected patch won't make it through code review until the release note is present.
How does this fit in with the existing practice of putting admin upgrade instructions into SchemaUpgrades/ (which get packaged in beaker-server)?
Do we drop the SchemaUpgrades/ stuff entirely, and use What's New for upgrade instructions also?
Does that mean it will end up with blobs of SQL all through it, like the SchemaUpgrades notes currently have?
What about the (admittedly rare) occasions when we have a Python script for doing data migration/fixing as part of an upgrade?
On 02/14/2013 08:38 AM, Dan Callaghan wrote:
First let me say, thank you Nick for setting this up, user-facing release notes have been sorely lacking.
Excerpts from Nick Coghlan's message of 2013-02-13 15:28:31 +1000:
The process is fairly simple: if you're making a user/admin facing change for 1.0, it must be captured in a reStructuredText file under "documentation/whats-new/release-1.0/". Any affected patch won't make it through code review until the release note is present.
How does this fit in with the existing practice of putting admin upgrade instructions into SchemaUpgrades/ (which get packaged in beaker-server)?
Whatever we do, we should still ensure a copy of the upgrade notes makes its way into beaker-server (even if only in plain text form)
Do we drop the SchemaUpgrades/ stuff entirely, and use What's New for upgrade instructions also?
That's a decent idea.
Does that mean it will end up with blobs of SQL all through it, like the SchemaUpgrades notes currently have?
But this wouldn't be a good outcome.
What about the (admittedly rare) occasions when we have a Python script for doing data migration/fixing as part of an upgrade?
We should definitely mention that.
How about we add a standard section to the release notes for "Upgrading an existing installation" (e.g. release-X.Y/upgrade-guide.rst) and use that instead of SchemaUpgrades?
For Beaker 1.0, we'd say something like "If upgrading from a version other than Beaker 0.11, see <ref to SchemaUpgrades>", while for subsequent releases, we'd reference back to the upgrade notes for those versions.
Alternatively, we can leave this alone for the moment, and just reference SchemaUpgrades from the What's New.
Cheers, Nick.
beaker-devel@lists.fedorahosted.org