project-team-guide/doc/source/repository.rst

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.

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: Retire Repository from the Governance Repository

First 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.

This patch will not pass the zuul until repo content is removed in Steps 3-5. Once repo content removal patch is merged, 'recheck' the governance patch to trigger the test again.

Step 2: 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.

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

Steps 3-5: Follow all three steps from OpenDev Manual

Follow the steps about Retiring a Project in the OpenDev Manual.

In step 1 of OpenDev Manual, keep the template official-openstack-repo-jobs besides noop-jobs, this is needed to sync changes to GitHub. It will be removed in step 3 of OpenDev Manual.

In step 1-2 of OpenDev Manual (1. Stop gating and 2. repo content removal) patch needs to merge without any depends-on but you need to use Needed-By governance patch submitted in Step 1.

In step 3 of OpenDev Manual patches, use Depends-On on governance patch submitted in Step 1.

Step 6: 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.

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

Step 7: Mark the deliverables as retired

For maintained openstack series, on openstack/releases, amend the related deliverable files to tag the project with the retired flag.

Example with deliverables/train/puppet-panko.yaml:

---
launchpad: puppet-panko
release-model: cycle-trailing
team: Puppet OpenStack
type: other
repository-settings:
  openstack/puppet-panko:
    flags:
      - retired
...

Even if a project is retired, stable branches will continue to follow the existing series life cycle and this flag will allow us to ignore this deliverable in some specific cases.

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 with the stable policy tag <https://governance.openstack.org/tc/reference/tags/stable_follows-policy.html> must be marked as deprecated. If project has no stable branch or does not follow the stable policy tag 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 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.

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

Step 3: Retire master branch

Step 3a: Use only noop jobs

Add noop jobs for master only in project-config repository and remove all 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
  check:
    jobs:
      - noop:
          branches: master
  gate:
    jobs:
      - noop:
          branches: master

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 3b: Remove project content

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

Step 3c: Remove noop jobs

Once the project content is retired, partially revert the change you merged earlier for project-config in step 2a 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 2a.

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

Step 4: 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.

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