79f8d631eb
We forgot to document the latest guidelines and include them in our project's documentation. This patch fixes that plus it modifies the tools/jsonToRst.py so that it takes into account the 2 new programs, added in the 2022.06 guidelines as next ones. In order to avoid this mistake in the future, the Internal Process Documentation is extended about the steps required to document a guideline. Change-Id: I0447adb2685a0766f7935e47816cee57a50e6d77
121 lines
5.0 KiB
ReStructuredText
121 lines
5.0 KiB
ReStructuredText
Internal Process Documentation
|
|
==============================
|
|
|
|
Here we document all internal (within the IWG group) actions needed in order
|
|
to release a new guideline.
|
|
This documentation should help to avoid mistakes and to ensure that every
|
|
guideline is released in a standardized way.
|
|
|
|
This document is based on
|
|
`OpenStack Interop Working Group Process 2021A <./2021A.rst/>`_ although it
|
|
focuses more on the internal (within the IWG group) actions, such as order of
|
|
reviews, their content and timing.
|
|
|
|
|
|
Actions done during a cycle
|
|
---------------------------
|
|
This section summarizes actions in a suggested order IWG team should focus on
|
|
during the cycle.
|
|
|
|
* See if we have any new tests (for projects currently covered by Interop) in
|
|
tempest which haven't been added to interop yet, (this script will help here
|
|
`<https://review.opendev.org/c/osf/interop/+/799201>`_)
|
|
|
|
* If there are new tests, decide whether they are worth to be included in any
|
|
(maybe new) capability.
|
|
|
|
* If yes, add them to a capability / create a new one.
|
|
|
|
* when creating a new capability make sure that required_since is empty -
|
|
it will be set once the capability gets under required (new ones are
|
|
under advisory)
|
|
|
|
* If not, add them to the exclude list with a brief explanation why
|
|
so that the test won't come up in a future release.
|
|
|
|
* See if we have any new deprecated tests in Tempest or if any tests got
|
|
removed from Tempest recently (only tests related to the projects under
|
|
Interop coverage concern us). E.g. go through merged patches within the
|
|
relevant time frame.
|
|
|
|
* If there are any deprecated tests, let's deprecate the capabilities which
|
|
contain the deprecated tests (move them from required to deprecated in the
|
|
relevant next files). Don't forget to **mention a related link** in the
|
|
commit message (f.e. tempest change which deprecated the tests).
|
|
|
|
* If there are any removed tests, verify whether the related capabilities
|
|
were deprecated already.
|
|
|
|
* If they were, consider moving the capabilities to removed section.
|
|
|
|
* If they were not, deprecate them. They will be removed in the next cycle.
|
|
|
|
* Watch out for any reported issues or skips (f.e. in the upstream CI) of tests
|
|
which are part of any capability which is currently under advisory. This info
|
|
will be crucial in the release process when we decide whether to move the
|
|
advisory capabilities to the required section.
|
|
|
|
Release process (starting 1 month before PTG)
|
|
---------------------------------------------
|
|
|
|
Changes to be done within next.json files are documented in this section.
|
|
|
|
1. Make sure tempest/<plugin> sha is correct
|
|
(test_repositories.tempest/<plugin>.reference)
|
|
2. Make sure values listed under os_trademark_approval are correct
|
|
(target_approval, replaces, releases)
|
|
3. Make sure required_since within lately added tests is equal to an empty
|
|
string ("") the guideline release and to the target_approval
|
|
4. Verify all flagged tests should be still flagged - unflag them otherwise
|
|
5. Verify all advisory tests we still want to be advisory, if not move them
|
|
accordingly
|
|
|
|
1. If you move a test from advisory (probably to required), set
|
|
required_since to the guideline release and to the target_approval
|
|
|
|
6. Check if any of the capabilities are deprecated.
|
|
7. Repeat the above process for every add-on's next file
|
|
8. Rename next.json to <target_release.json> - in case there are other changes
|
|
in the next.json file, do this step in a separate patch as the rename appear
|
|
in gerrit as a new file which makes it harder to see other changes within
|
|
the file.
|
|
|
|
1. Edit required_platform_components.source references in the add-on next
|
|
files so that they point to the new platform guideline being released
|
|
(next.json -> <target_release>.json)
|
|
|
|
9. Run the following script to update the documentation. It will generate a new
|
|
file named *all.<target_release>.rst* under *doc/source/guidelines/*
|
|
|
|
.. code-block:: console
|
|
|
|
$ tools/jsonToRst.py --all <target_release>
|
|
|
|
1. Edit *doc/source/guidelines/index.rst* file to make the new guideline doc
|
|
visible - move the latest guideline from **Latest Guideline** section to
|
|
the **Previous Guidelines** section and put the new guideline ot the
|
|
**Latest Guideline** section.
|
|
|
|
10. Add PTL or project representatives for each project that next file is
|
|
covering, to review the changes.
|
|
11. Add Foundation Marketplace representatives to review the proposed
|
|
guidelines.
|
|
12. Change status from draft to approved. (after committee review - that will
|
|
be in separate patch) -> ~ 3 months after PTG
|
|
|
|
1. Run the following script to reflect the status change in the documentation
|
|
|
|
.. code-block:: console
|
|
|
|
$ tools/jsonToRst.py --all <target_release>
|
|
|
|
13. Copy and rename the newly created .json files to next.json files
|
|
(<add-on>.next.json) - separate patch
|
|
|
|
1. Change status from approved to draft
|
|
2. Run the following script to update the documentation.
|
|
|
|
.. code-block:: console
|
|
|
|
$ tools/jsonToRst.py --all next
|