From cca243172e526f131643f407c8a8e6cd0b2e8bc7 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Mon, 20 Mar 2017 08:01:23 -0500 Subject: [PATCH] Document the duties of the Release CPL I've written some documentation around the role and duties of the release CPL due to the fact that I'm leaving this role, Glance, and the larger OpenStack community. This should provide context for both new and old members of the Glance community as to their responsibilities and what is expected of them. It also passes on some experience-driven advice as to what to do to ensure a better Glance release for all. Co-Authored-By: Hemanth Makkapati Change-Id: I8d580d05668d1560b027736fbc1fb1dd36edbabe --- doc/source/contributing/index.rst | 1 + doc/source/contributing/release-cpl.rst | 278 ++++++++++++++++++++++++ 2 files changed, 279 insertions(+) create mode 100644 doc/source/contributing/release-cpl.rst diff --git a/doc/source/contributing/index.rst b/doc/source/contributing/index.rst index a68e3e8182..068dfc3a1f 100644 --- a/doc/source/contributing/index.rst +++ b/doc/source/contributing/index.rst @@ -28,6 +28,7 @@ Policies documentation minor-code-changes refreshing-configs + release-cpl .. bugs contributor-onboarding core-reviewers diff --git a/doc/source/contributing/release-cpl.rst b/doc/source/contributing/release-cpl.rst new file mode 100644 index 0000000000..f17a87c3d0 --- /dev/null +++ b/doc/source/contributing/release-cpl.rst @@ -0,0 +1,278 @@ +================== +Glance Release CPL +================== + +So you've volunteered to be the Glance Release Cross-Project Liaison (CPL) and +now you're worried about what you've gotten yourself into. Well, here are some +tips for you from former release CPLs. + +You will be doing vital and important work both for Glance and OpenStack. +Releases have to be available at the scheduled milestones and RC dates because +end users, other OpenStack projects, and packagers rely on releases being +available so they can begin their work. Missing a date can have a cascading +effect on all the people who are depending on the release being available at +its scheduled time. Sounds scary, I know, but you'll also get a lot of +satisfaction out of having a key role in keeping OpenStack running smoothly. + + +Who You Have to Be +================== + +You do **not** have to be: + +- The PTL + +- A core reviewer + +- A stable-branch core reviewer/maintainer + +You **do** have to be: + +- A member of the Glance community + +- A person who has signed the OpenStack CLA (or whatever is in use at the time + you are reading this) + +- Someone familiar with or willing to learn git, gerrit, etc. + +- Someone who will be comfortable saying "No" when colleagues want to sneak + just one more thing in before a deadline. + +- Someone willing to work with the release team on a regular basis and attend + their `weekly meeting`_. + + Just as the stable maintenance team is responsible for the stability and + quality of the stable branches, the release CPL must take on responsibility + for the stability and quality of every release artifact of Glance. If you + are too lenient with your colleagues, you might be responsible for + introducing a catastrophic or destabilizing release. Suppose someone, + possibly even the PTL, shows up right before RC1 with a large but probably + innocuous change. Even if this passes the gate, you should err on the side + of caution and ask to not allow it to merge. + (This has happened `before `_ ) + +A Release CPL has authority within the Glance project. They have authority +through two measures: + +- Being the person who volunteered to do this hard work + +- Maintaining a healthy relationship with the PTL and their Glance colleagues. + +Use this authority to ensure that each Glance release is the best possible. +The PTL's job is to lead technical direction, your job is to shepherd cats and +help them focus on the priorities for each release. + + +What This Does Not Grant You +============================ + +Volunteering to be Release CPL does not give you the right to be a Glance Core +Reviewer. That is a separate role that is determined based on the quality of +your reviews. You should be primarily motivated by wanting to help the team +ship an excellent release. + + +Get To Know The Release Team +============================ + +OpenStack has teams for most projects and efforts. In that vein, the release +team works on tooling to make releasing projects easier as well as verifying +releases. As CPL it is your job to work with this team. At the time of this +writing, the team organizes in ``#openstack-release`` and has a `weekly +meeting`_. Idling in their team channel and attending the meeting are two very +strongly suggested (if not required) actions for the CPL. You should introduce +yourself well in advance of the release deadlines. You should also take the +time to research what actions you may need to take in advance of those +deadlines as the release team becomes very busy around those deadlines. + + +Familiarize Yourself with Community Goals +========================================= + +Community Goals **are** Glance Goals. They are documented and tracked in the +`openstack/governance`_ repository. In Ocata, for example, the CPL assumed the +responsibility of monitoring those goals and reporting back to the TC when +we completed them. + +In my opinion, it makes sense for the Release CPL to perform this task because +they are the ones who are keenly aware of the deadlines in the release +schedule and can remind the assigned developers of those deadlines. + +It also is important for the Release CPL to coordinate with the PTL to ensure +that there are project-specific deadlines for the goals. This will ensure the +work is completed and reviewed in a timely fashion and hopefully early enough +to catch any bugs that shake out of the work. + + +Familiarize Yourself with the Release Tooling +============================================= + +The Release Team has worked to automate much of the release process over the +last several development cycles. Much of the tooling is controlled by updating +certain YAML files in the `openstack/releases`_ repository. + +To release a Glance project, look in the ``deliverables`` directory for the +cycle's codename, e.g., ``pike``, and then look for the project inside of +that. Update that using the appropriate syntax and after the release team has +reviewed your request and approved it, the rest will be automated for you. + +For more information on release management process and tooling, refer to +`release management process guide`_ and `release management tooling guide`_. + + +Familiarize Yourself with the Bug Tracker +========================================= + +The `bug tracker`_ is the best way to determine what items are slated to get +in for each particular milestone or cycle release. Use it to the best of its +capabilities. + +Release Stability and the Gate +============================== + +As you may know at this point, OpenStack's Integrated Gate will begin to +experience longer queue times and more frequent unrelated failures around +milestones and release deadlines (as other projects attempt to sneak things +in at the last minute). + +You may help your colleagues (and yourself) if you advocate for deadlines on +features, etc., at least a week in advance of the actual release deadline. +This can apply to all release deadlines (milestone, release candidate, final). +If you can stabilize your project prior to the flurry of activity, you will +ship a better product. You can also then focus on bug fixing reviews in the +interim between your project priorities deadline and the actual release +deadline. + + +Checklist +========= + +The release team will set dates for all the milestones for each release. The +release schedule can be found from this page: +https://releases.openstack.org/index.html +There are checklists to follow for various important release aspects: + + +Glance Specific Goals +--------------------- + +While the release team sets dates for community-wide releases, you should work +with the PTL to set Glance specific deadlines/events such spec proposal freeze, +spec freeze, mid-cycle, bug squash and review squash etc. Also, you can set +additional deadlines for Glance priorities to ensure work is on-track for a +timely release. + +You are also responsible for ensuring PTL and other concerned individuals are +aware and reminded of the events/deadlines to ensure timely release. + + +Milestone Release +----------------- + +The release schedule for the current cycle will give you a range of dates for +each milestone release. It is your job to propose the release for Glance +sometime during that range and ensure the release is created. This means the +following: + +- Showing up at meetings to announce the planned date weeks in advance. + + Your colleagues on the Glance team will need at least 4 weeks notice so they + can plan and prioritize what work should be included in the milestone. + +- Reminding your colleagues what the stated priorities for that milestone + were, their progress, etc. + +- Being inflexible in the release date. As soon as you pick your date, stick + to it. If a feature slips a milestone to the next, it is not the end of the + world. It is not ideal, but Glance *needs* to release its milestone as soon + as possible. + +- Proposing the release in a timely and correct fashion on the day you stated. + You may have colleagues try to argue their case to the release team. This is + when your collaboration with the PTL will be necessary. The PTL needs to + help affirm your decision to release the version of the project you can on + the day you decide it. + +- Release ``glance_store`` and ``python-glanceclient`` at least once per + milestone. + +- Write `release notes`_ + +Release Candidate Releases +-------------------------- + +The release candidate release period is similarly scoped to a few days. It is +even more important that Glance release during that period. To help your +colleagues, try to schedule this release as close to the end of that range as +possible. Once RC1 is released, only bugs introduced since the last milestone +that are going to compromise the integrity of the release should be merged. +Again, your duties include all of the Milestone Release duties plus the +following: + +- When proposing the release, you need to appropriately configure the release + tooling to create a stable branch. If you do not, then you have not + appropriately created the release candidate. + +- Keeping a *very* watchful eye on what is proposed to and approved for master + as well as your new stable branch. Again, automated updates from release + tooling and *release critical* bugs are the only things that should be + merged to either. + +- If release critical bugs are found and fixed, proposing a new release + candidate from the SHA on the stable branch. + +- Write `release notes`_ + +- Announce that any non-release-critical changes won't be accepted from this + point onwards until the final Glance release is made. Consider adding -2 on such + reviews with good description to prevent further updates. This also helps in + keeping the gate relatively free to process the release-critical changes. + + +Final Releases +-------------- + +The release team usually proposes all of the projects' final releases in one +patch based off the final release candidate. After those are created, some +things in Glance need to be updated immediately. + +- Right after cutting the stable branch, Glance release version (not the API + version) must be bumped so that all further development is attributed to the + next release version. This could be done by adding an empty commit with commit + message containing the flag ``Sem-Ver: api-break`` to indicate a version. Here + is a sample commit attempting to `bump the release version`_. +- The migration tooling that Glance uses relies on some constants defined in + `glance/db/migration.py`_. Post final release, those need *immediate* + updating. + + +Acknowledgements +---------------- +This document was originally written by Ian Cordasco. It's maintained and +revised by the Glance Release CPLs: + +- Ian Cordasco, Release CPL for Ocata +- Hemanth Makkapati, Release CPL for Pike + + +.. links +.. _weekly meeting: + http://eavesdrop.openstack.org/#Release_Team_Meeting +.. _openstack/governance: + https://git.openstack.org/cgit/openstack/governance +.. _openstack/releases: + https://git.openstack.org/cgit/openstack/releases +.. _StoryBoard: + https://storyboard.openstack.org/ +.. _glance/db/migration.py: + https://github.com/openstack/glance/blob/master/glance/db/migration.py +.. _release management process guide: + https://docs.openstack.org/project-team-guide/release-management.html +.. _release management tooling guide: + http://git.openstack.org/cgit/openstack/releases/tree/README.rst +.. _bug tracker: + https://bugs.launchpad.net/glance +.. _release notes: + https://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes +.. _bump the release version: + https://review.openstack.org/#q,I21480e186a2aab6c54f7ea798c215660bddf9e4c,n,z