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.