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.