Repository Handling

Project Renames

If you rename a project to move out from “openstack” namespace to any other namespace, follow this OpenStack TC resolution.

For a project being added to existing official OpenStack project: Create an openstack/governance change and add a “Depends-On: project-change-url” of the change you make in the following steps to the commit message, and add a comment in the openstack/project-config change that references the governance change. You will also make sure the PTL has expressed approval for the addition in some way.

If you rename an existing official OpenStack project, add the openstack/governance change as dependency on the openstack/project-config change so that it can merge after the rename is done.

Do not forget to update the Zuul job definitions. This is important to keep the Zuul jobs definition correct and utilize the CI/CD infra resources in better way. You need to find if retiring repository is used in Zuul job definition on master and stable branches as required-projects or any other place. Searching in master jobs is easy via codesearch but searching in stable branches is tricky. Make sure you cleanup all the stable branches including branches in Extended Maintenance state. Otherwise it will leads to the Zuul config errors which can be found in the Zuul config errors list

The detailed steps for renaming a project are documented in the section Project Renames of the OpenDev Manual.

Retiring a Repository

If you need to retire a project and no longer accept patches - for both master and stable branches -, it is important to communicate that to both users and contributors. The following steps will help you wind down a project gracefully.

Note

The following sections are really separate steps. If your project has jobs set up, you need to submit four different changes as explained below and in the OpenDev Manual. We recommend to link these changes with “Depends-On:” and “Needed-By:” headers.

Step 1: End Project Gating

Follow the Step 1 about End Project Gating in the OpenDev Manual.

Note

Please keep the official-openstack-repo-jobs template to sync retirement to the GitHub mirrors.

Step 2: Remove Project Content

Follow the Step 2 about Remove Project Content in the OpenDev Manual.

Step 3: Retire Repository from the Governance Repository

This step is to get the agreement in the Technical Committee by retiring the repository from the reference/projects.yaml file and add it to the file reference/legacy.yaml in the openstack/governance repository. Note that if the project was recently active, this may have implications for automatic detection of ATCs.

We need to wait for this patch to merge first before proceeding next. Main goal here is to get the Technical Committee agreement and governance scripts to check the proper retirement which will help us to avoid any re-retirement work.

NOTE: use Depends-On on Remove Project Content patch submitted in Step 2.

Step 4: Stop requirements syncing (if set up)

Submit a review to the openstack/requirements project removing the project from projects.txt. This needs to happen for stable branches as well.

NOTE: use Depends-On on governance patch submitted in Step 3.

Step 5: Remove repository references

Make sure all the reference to the retiring repository has been removed properly. A few of the places to audit and update are:

  1. Check all the projects source code and documentation if there is any reference of retiring repository. Use codesearch to check it.

  2. Zuul job definitions:

    This is important to keep the Zuul jobs definition correct and utilize the CI/CD infra resources in better way. You need to find if retiring repository is used in Zuul job definition on master and stable branches as required-projects or any other place. Searching in master jobs is easy via codesearch but searching in stable branches is tricky. Make sure you cleanup all the stable branches including branches in Extended Maintenance state. Otherwise it will leads to the Zuul config errors which can found in the Zuul config errors list

NOTE: use Depends-On on governance patch submitted in Step 3.

Steps 6: Remove Project from Infrastructure Systems

Follow the steps about Remove Project from Infrastructure System in the OpenDev Manual, but instead of the ACL file mentioned there use /home/gerrit2/acls/openstack/retired.config so that the TC will still be able to make content adjustments in the future.

NOTE: use Depends-On on governance patch submitted in Step 3.

Step 7: Remove docs.openstack.org content

Inform users that reach the docs.openstack.org page of your repository that it is retired.

For this, add the name of your repository to the _RETIRED_REPOS list in the file tools/www-generator.py in the openstack/openstack-manuals repository. Once the change merged, the URL https://docs.openstack.org/openstack/<projectname>/latest will redirect to the repositories’ README.rst file.

NOTE: use Depends-On on governance patch submitted in Step 3.

Step 8: Retire deliverables in releases repository

Given that this project is being retired, there will be no more releases. Thus you must do two tasks in the openstack/releases repository.

First, completely remove the deliverable’s yaml file from the directory corresponding to the current development cycle. For example, if your deliverable is puppet-panko and the current development cycle is Ussuri, you must delete deliverables/ussuri/puppet-panko.yaml.

Next, if your deliverable has supported or unmaintained stable branches, for example, stable/train, you must EOL it with the latest hash that exists on that stable branch.

Example, EOL Magnum up to Xena

  ---
- version: xena-eol
  projects:
    - repo: openstack/magnum
      hash: c5f8c78ef3ad93c830b5dc49ab6053252333b077
  ...

NOTE: use Depends-On on governance patch submitted in Step 3.

Step 9: Update openstack-map to remove the retired project

If the retired repository/project is listed in openstack-map , you need to remove it from there.

For Example: https://review.opendev.org/c/openinfra/openstack-map/+/764544

Use Depends-On on governance patch submitted in Step 1.

Deprecating a Repository

If you only want to stop development of the master branch but keep stable branches, you need to do a slightly different approach.

Deprecating the project or repository is different than removal. If the project want to stop the development on master branch but support the stable branches with bug fixes, then project must be marked as deprecated. If project has no stable branch then you have option to go with removal process directly.

Step 1: Mark the Repository as Deprecated in the Governance Repository

Mark the repository in the reference/projects.yaml file of the openstack/governance repository as deprecated with adding a line:

deprecated: <deprecated-cycle-name>
release-management: deprecated

Step 2: Stop requirements syncing (if set up)

Submit a review to the openstack/requirements project removing the project from projects.txt.

NOTE: use Depends-On on governance patch submitted in Step 1.

Step 3: Stop deliverables from the current development branch

We’re going to be retiring the master branch of the project and won’t be doing any releases from it. Suppose that the current development cycle is 2999.2 and the release nickname is “Xylophone”. Submit a review to the openstack/releases repository that removes the deliverable’s yaml file from the deliverables/xylophone/ directory.

For a recent example, here’s the gerrit review that deprecated cinderlib’s deliverables during the Caracal development cycle: https://review.opendev.org/c/openstack/releases/+/904862

NOTE: use Depends-On on governance patch submitted in Step 1.

Step 4: Retire master branch

If the repository is branchless (for example, Tempest and its plugins) and its master branch content needs to support the other deliverables stable branch until they are retired or reach EOL, then you can skip this Step 3 and update only README.rst file to reflect the deprecation notes.

Step 4a: Use only noop jobs

Add noop-jobs template to zuul.d/projects.yaml for master only in project-config repository and remove all other templates temporarily with exception of official-openstack-repo-jobs and pypi release template if any. If your project has publish-to-pypi template present, then change it to publish-to-pypi-stable-only. It should look something like this:

- project:
  name: openstack/<projectname>
  templates:
    - official-openstack-repo-jobs
    - publish-to-pypi-stable-only
    - noop-jobs

Adjust the project description. Find the entry for your project in gerrit/projects.yaml and look for the line which defines the description, prefix it with DEPRECATED, like this:

description: DEPRECATED, existing project description

Step 4b: Remove project content

Follow step 2 about Removing project content in the OpenDev Manual.

Step 4c: Remove noop jobs

Once the project content is retired, partially revert the change you merged earlier for project-config in step 3a and re-add templates and jobs you need so that you can merge content on stable branches. Please ensure you keep the DEPRECATED, prefix you added to project description in step 3a.

NOTE: In all the patches, use Depends-On on governance patch submitted in Step 1.

Step 5: Remove docs.openstack.org content

Inform users that reach the docs.openstack.org page of your repository that it is deprecated.

For this, add the name of your repository to the _RETIRED_REPOS list in the file tools/www-generator.py in the openstack/openstack-manuals repository. Once the change merged, the URL https://docs.openstack.org/openstack/<projectname>/latest will redirect to the repositories’ README.rst file.

Also, remove the project from the list in the www/project-data/latest.yaml in the openstack/openstack-manuals repository if present. That will remove the project from the list of new releases.

NOTE: use Depends-On on governance patch submitted in Step 1.