From 9536edb1fcc23c2df4d4886c1b1bbb354bb8c121 Mon Sep 17 00:00:00 2001 From: Thierry Carrez Date: Thu, 22 Mar 2018 16:10:28 +0100 Subject: [PATCH] Base ladder content for CONTRIBUTING.rst Post base ladder content in our CONTRIBUTING.rst file, a baby step in getting more people involved with release management. Change-Id: Ic20fb20870bdae2cae126f316c9bd0fb2487d0a1 --- CONTRIBUTING.rst | 129 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 121 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a9c09b938a..fc197de585 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,12 +1,125 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps in this page: +====================================== +Release management contribution ladder +====================================== - https://docs.openstack.org/infra/manual/developers.html +Getting involved with release management can feel a bit overwhelming. +To set expectations reasonably, we define 4 levels of engagement. -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: +Stage 0 - Review release requests +================================= - https://docs.openstack.org/infra/manual/developers.html#development-workflow +This stage does not require any special rights. You should just review +release requests (modifications of files in deliverables/ directory in +the releases repository), apply the release review rules and vote. + +Release review guidelines +------------------------- + +Three test jobs run for every release request: + +* openstack-tox-validate checks for proper yaml format and schema validation + and checks for things like proper job types and valid release note links + +* releases-tox-list-changes finds included commits, lists PTL and release + liaison, requirements changes, and open reviews for docs and release notes + +* build-openstack-sphinx-docs performs a build of the releases website and + checks for errors. + +You should: + +* check that the version bump matches semver rules. In particular, a .Z bump + means only bugfixes should be listed in list-changes. + +* check the output of the test jobs. + +* Place your vote based on whether you think the request should be accepted + as-is or not. + + +Stage 1 - Approving release requests +==================================== + +At this stage you will be trusted with CodeReview+2 and Workflow+1 votes +on the releases repository, giving you the ability to trigger releases. +You will need a base understanding of the release machinery, and know +to refrain from approving when unsure. + +Release infrastructure primer +----------------------------- + +What happens when a release is approved? Release infrastructure is divided +into two steps, triggered by different, but related events. + +The first step is triggered by the release request being merged into the +releases repository, starting a series of jobs in the "post" pipeline +of the releases repository: + +Release request merged + | + +-------v-----------------------+ + Post pipeline (releases repo) + +---+-----------------------+---+ + | | + v v ++-------+-------+ +-------+-------+ +| tag | | publish-docs | +| | | | +| (pushes tags | | (to releases | +| to each repo) | | website) | +| | | | ++-------+-------+ +---------------+ + +The second step is triggered by the creation of the tag, creating a series +of jobs in the "release" pipeline (or "pre-release" pipeline, in case of beta +versions) of the repository the tag landed in: + + Tag is created + | + +----v------------------------------------+ + Release pipeline (each repo) + +----+---------------+---------------+----+ + | | | + v v v + +-----+-----+ +-----+-----+ +-----+-----+ + | release | | announce | | propose | + | | | | |constraints| + |(builds | | (sends | | update | + | tarball | | email) | | | + | & uploads | | | +-----------+ + | it) | +-----------+ + +-----------+ + +Note that a single release request can create multiple tags in different +repositories, triggering that second stage in multiple repositories. + +Jobs in step 2 need information from the release request (like series name, +or whether to upload to pypi). We use metadata in the git tag itself to pass +that information: the "tag" job in step 1 records the information in the tag, +and the jobs in step 2 retrieve that information directly from the tag. + + +Checklist before approving a release +------------------------------------- + +* You should only approve release requests. +* You should check that release is approved by PTL or release liaison +* You should check that infrastructure is not currently experiencing issues +* You should check that we are not in any freeze period +* If unsure, it is better to wait for a second opinion that to press + Workflow+1 directly. + + +Stage 2 - Knowing the release cycle process +=========================================== + +At this stage you will be able to help drive the release cycle process, +send reminder emails and answer questions from release liaisons. + + +Stage 3 - Understanding the Release Automation Infrastructure +============================================================= + +At this stage you will be able to debug complex release infrastructure +failures, and review/approve release tooling changes. -Pull requests submitted through GitHub will be ignored.