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.
--
Nick Coghlan
Red Hat Infrastructure Engineering & Development, Brisbane
Python Applications Team Lead
Beaker Development Lead (
http://beaker-project.org/)
PulpDist Development Lead (
http://pulpdist.readthedocs.org)