From 2fbc89387dc05547184344e82edfcef724a8df42 Mon Sep 17 00:00:00 2001 From: Thierry Carrez Date: Thu, 22 Jul 2021 15:31:25 +0200 Subject: [PATCH] Move release team ladder & infra into proper page The release team involvement ladder and infrastructure primer were hard to find in CONTRIBUTING.rst. It's better to move them next to the rest of the team documentation. Change-Id: I3859ce431711cef5176a3ea34b9433bd06d51447 --- CONTRIBUTING.rst | 131 ++------------------- doc/source/index.rst | 2 + doc/source/reference/join_release_team.rst | 61 ++++++++++ doc/source/reference/release_infra.rst | 54 +++++++++ 4 files changed, 128 insertions(+), 120 deletions(-) create mode 100644 doc/source/reference/join_release_team.rst create mode 100644 doc/source/reference/release_infra.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index dc5a46b4e2..c497c4de57 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,126 +1,17 @@ -====================================== -Release management contribution ladder -====================================== +If you would like to contribute to the development of OpenStack, you must +follow the steps in this page: -Getting involved with release management can feel a bit overwhelming. -To set expectations reasonably, we define 4 levels of engagement. + https://docs.openstack.org/infra/manual/developers.html -Stage 0 - Review release requests -================================= +If you already have a good understanding of how the system works and your +OpenStack accounts are set up, you can skip to the development workflow +section of this documentation to learn how changes to OpenStack should be +submitted for review via the Gerrit tool: -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. + https://docs.openstack.org/infra/manual/developers.html#development-workflow -Release review guidelines -------------------------- +Pull requests submitted through GitHub will be ignored. -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 "tag" pipeline and the "release" pipeline (or "pre-release" -pipeline, in case of beta versions) of the repository the tag landed in: - - Tag is created ----------------------------------------------- - | | - +----v------------------------------------+ +----------v-----------+ - Release pipeline (each repo) Tag pipeline (each repo) - +----+---------------+---------------+----+ +----------------------+ - | | | | - v v v v - +-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+ - | release | | announce | | propose | | publish | - | | | | |constraints| | release | - |(builds | | (sends | | update | | notes | - | 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 the release pipeline 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. +See the release team documentation at: + https://releases.openstack.org/#documentation diff --git a/doc/source/index.rst b/doc/source/index.rst index af3b06d9f1..11cf6bc14d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -174,7 +174,9 @@ documentation: reference/using reference/release_models reference/deliverable_types + reference/join_release_team reference/reviewer_guide + reference/release_infra reference/process .. _`openstack/releases`: https://opendev.org/openstack/releases diff --git a/doc/source/reference/join_release_team.rst b/doc/source/reference/join_release_team.rst new file mode 100644 index 0000000000..11f2273be4 --- /dev/null +++ b/doc/source/reference/join_release_team.rst @@ -0,0 +1,61 @@ +====================== +Join the release team! +====================== + +Communication channels +====================== + +The release team communicates and meets on the `#openstack-release`_ channel +on OFTC IRC, on the `openstack-discuss mailing-list`_ using the [release] +subject prefix. + +.. _`#openstack-release`: https://webchat.oftc.net/?channels=openstack-release + +.. _`openstack-discuss mailing-list`: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss + +The engagement ladder +===================== + +Getting involved with release management can feel a bit overwhelming. +To set expectations reasonably, we define 4 levels of engagement. + +Stage 0 - Review release requests +--------------------------------- + +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. + +See the :doc:`reviewer_guide` for more review guidelines. + +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 :doc:`release_infra`, and know +to refrain from approving when unsure. + +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 :doc:`release_infra` +failures, and review/approve release tooling changes. + diff --git a/doc/source/reference/release_infra.rst b/doc/source/reference/release_infra.rst new file mode 100644 index 0000000000..6593c399ae --- /dev/null +++ b/doc/source/reference/release_infra.rst @@ -0,0 +1,54 @@ +====================== +Release infrastructure +====================== + +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 "tag" pipeline and the "release" pipeline (or "pre-release" +pipeline, in case of beta versions) of the repository the tag landed in:: + + Tag is created ----------------------------------------------- + | | + +----v------------------------------------+ +----------v-----------+ + Release pipeline (each repo) Tag pipeline (each repo) + +----+---------------+---------------+----+ +----------------------+ + | | | | + v v v v + +-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+ + | release | | announce | | propose | | publish | + | | | | |constraints| | release | + |(builds | | (sends | | update | | notes | + | 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 the release pipeline 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.