openinfra/interop
Code Issues Proposed changes
interop/doc/source/process/InternalProcessDoc.rst
Martin Kopec 79f8d631eb Document 2022.06 guidelines 
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
2022-10-11 16:23:02 +02:00

5.0 KiB
Raw Blame History

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 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
  1. Check if any of the capabilities are deprecated.
  2. Repeat the above process for every add-on's next file
  3. 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)

  1. Run the following script to update the documentation. It will generate a new file named all.<target_release>.rst under doc/source/guidelines/

    $ 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.
  1. Add PTL or project representatives for each project that next file is covering, to review the changes.
  2. Add Foundation Marketplace representatives to review the proposed guidelines.
  3. 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
$ tools/jsonToRst.py --all <target_release>
  1. 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.
$ tools/jsonToRst.py --all next