<div dir="ltr">Hi docs peeps, wanted to be sure you see and understand this important change for releases and release notes. <div><br></div><div>Anne</div><div><br></div><div><br><div class="gmail_quote">---------- Forwarded message ----------<br>From: <b class="gmail_sendername">Doug Hellmann</b> <span dir="ltr"><<a href="mailto:doug@doughellmann.com">doug@doughellmann.com</a>></span><br>Date: Tue, Nov 3, 2015 at 1:46 PM<br>Subject: [openstack-dev] [release] new change management tools and processes for stable/liberty and mitaka<br>To: openstack-dev <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br><br><br>As we discussed at the summit, the release management team is<br>
modifying our change management tracking tools and processes this<br>
cycle. This email is the official announcement of those changes,<br>
with more detail than we provided at the summit.<br>
<br>
In past cycles, we have used a combination of Launchpad milestone<br>
pages and our wiki to track changes in releases. We used to pull<br>
together release notes for stable point releases at the time of<br>
release. Most of that work fell to the stable maintenance and release<br>
teams. Similarly, the release managers worked with PTLs and release<br>
liaisons at each milestone checkpoint to update Launchpad to<br>
accurately reflect the work completed at each stage of development.<br>
It's a lot of work to fix up Launchpad and assemble the notes and<br>
make sure they are accurate, which has caused us to be a bottleneck<br>
for clear and complete communication at the time of the release.<br>
We have been looking for ways to reduce that effort for these tasks<br>
and eliminate the bottleneck for some time.<br>
<br>
This cycle, to address these problems for our ever-growing set of<br>
projects, the release management team is introducing a new tool for<br>
handling release notes as files in-tree, to allow us to simply and<br>
continuously build the release notes for stable branch point releases<br>
and milestones on the master branch. The idea is to use small YAML<br>
files, usually one per note or patch, to avoid merge conflicts on<br>
backports and then to compile those files in a deterministic way<br>
into a more readable document for readers. Files containing release<br>
notes can be including in patches directly, or you can create a<br>
separate patch with release notes if you want to document a feature<br>
than spans several patches. The tool is called Reno, and it currently<br>
supports ReStructuredText and Sphinx for converting note input files<br>
to HTML for publication. Reno is git branch-aware, so we can have<br>
separate release notes documents for each release series published<br>
together from the master build.<br>
<br>
The documentation for Reno, including design principles and basic<br>
usage instructions, is available at [1]. For now we are focusing<br>
on Sphinx integration so that release notes are published online.<br>
We will add setuptools integration in a future version of Reno so<br>
that the release notes can be built with the source distribution.<br>
<br>
As part of this rollout, I will also be updating the settings for<br>
the gerrit hook script so that when a patch with "Closes-Bug" in<br>
the commit message is merged the bug will be marked as "Fix Released"<br>
instead of "Fix Committeed" (since "Fix Committed" is not a closed<br>
state). When that work is done, I'll send another email to let PTLs<br>
know they can go through their existing bugs and change their status.<br>
<br>
We are ready to start rolling out Reno for use with Liberty stable<br>
branch releases and in master for the Mitaka release. We need the<br>
release liaisons to create and merge a few patches for each project<br>
between now and the Mitaka-1 milestone.<br>
<br>
1. We need one patch to the master branch of the project to add the<br>
instructions for publishing the notes as part of the project<br>
sphinx documentation build. An example patch for Glance is in<br>
[2].<br>
<br>
2. We need another patch to the stable/liberty branch of the project<br>
to set up Reno and introduce the first release note for that<br>
series. An example patch for Glance is in [3].<br>
<br>
3. Each project needs to turn on the relevant jobs in project-config.<br>
An example patch using Glance is in [4]. New patches will need<br>
to be based on the change that adds the necessary template [5],<br>
until that lands.<br>
<br>
4. Reno was not ready before the summit, so we started by using the<br>
wiki for release notes for the initial Liberty releases. We also<br>
need liaisons to convert those notes to reno YAML files in the<br>
stable/liberty branch of each project.<br>
<br>
Please use the topic "add-reno" for all patches so we can track<br>
adoption.<br>
<br>
Once those merge, project teams can stop using Launchpad for tracking<br>
completed work. We will still use Launchpad for bug reports, for<br>
now. If a team wants to continue using it for tracking blueprints,<br>
that's fine. If a team wants to use Launchpad for scheduling work<br>
to be done in the future, but not for release tracking, that is<br>
also fine. The release management team will no longer be reviewing<br>
or updating Launchpad as part of the release process.<br>
<br>
Thanks,<br>
Doug<br>
<br>
[1] <a href="http://docs.openstack.org/developer/reno/" rel="noreferrer" target="_blank">http://docs.openstack.org/developer/reno/</a><br>
[2] <a href="https://review.openstack.org/241323" rel="noreferrer" target="_blank">https://review.openstack.org/241323</a><br>
[3] <a href="https://review.openstack.org/241322" rel="noreferrer" target="_blank">https://review.openstack.org/241322</a><br>
[4] <a href="https://review.openstack.org/241344" rel="noreferrer" target="_blank">https://review.openstack.org/241344</a><br>
[5] <a href="https://review.openstack.org/241343" rel="noreferrer" target="_blank">https://review.openstack.org/241343</a><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>