Pulp

# Release Guide

The following guide provides step-by-step instructions for releasing pulpcore and most plugins.

Releases **always** happen on the X.Y branch.

## Preparing a Y-release

These steps are specific for releasing a y-release.

1. If [plugin_template/CHANGES](https://github.com/pulp/plugin_template/tree/master/CHANGES) dir is not empty: [build a new changelog and tag the plugin_template](https://github.com/pulp/plugin_template#tagging-plugin_template).

2. Update master branch with the latest GHA config from plugin_template

3. Run the "Create New Release Branch" from `master` branch. You need to specify the name of the new branch (e.g.: 1.7).

4. Checkout the new branch locally.

5. Update the upper bound of pulpcore in requirements.txt.

6. Update template_config.yml with new values for "pulpcore_branch" and "pulpcore_pip_version_specifier". 

7. Re-run plugin-template (e.g.: `./plugin-template --github pulp_file`).

8. Commit changes and make a PR against the new branch. Merge the PR.

## Releasing (Start here for Z stream)

1. Create a Sprint/Milestone (Not Shared) with the name of the release, e.g. 1.7.0. You can do this [here](https://pulp.plan.io/projects/pulp/settings/versions) for pulpcore. 

2. Go to the Release Pipeline workflow (for pulpcore, this is at https://github.com/pulp/pulpcore/actions/workflows/release.yml) and start a new release by clicking the `Run Workflow` button and entering the release branch and the release tag you want to release (e.g.: 1.7.0).

3. Monitor the job. Ensure it creates the tag, the pypi release, the client releases on pypi and rubygems, and updates the docs on docs.pulpproject.org.

4. Merge the changelog PR produced by the Release Pipeline workflow into `master` branch.

5. The release script should do all the Redmine steps below, just check that it's complete.

  - Ensure all tickets are at MODIFIED and in the "pulpcore" project. Clean them up if not.

  - Set all tickets named in the changelog to CLOSED - CURRENT RELEASE

  - Set the Sprint/Milestone to the one created \^

  - "close" the milestone, that is done [here](https://pulp.plan.io/projects/pulp/settings/versions)

6. If doing a Y-release check for any issues still at MODIFIED. Ping any assignees/teams to close out these issues. Ideally, there should be no issues still at MODIFIED.

7. Announce to https://discourse.pulpproject.org/ and pulp-list@redhat.com with a summary of all the changes.

8. If you did a pulpcore y-release, update the supported-releases.json file [here](https://raw.githubusercontent.com/pulp/pulp-ci/master/ci/config/releases/supported-releases.json) to the 3.y version in a PR like [this one](https://github.com/pulp/pulp-ci/pull/696). This drives a javascript banner on docs.pulpproject.org and if not set correctly the latest, supported Y-release will show a banner (incorrectly) that this version is unsupported.

9. If releasing pulpcore, you must also release pulp_installer. The release guide is [here](https://github.com/pulp/pulp_installer/blob/master/RELEASING.md).

10. Start a "Publish OCI Images" workflow with the branch matching the corresponding pulpcore minor release to get the changes in the single container. You can do this at https://github.com/pulp/pulp-oci-images/actions/workflows/publish_images.yaml

# Releasing a Plugin

## Preparing a Y-release

1. Update the CI config and workflows by running `./plugin-template --github PLUGIN_NAME`.

2. Pin the upper bound of pulpcore in requirements.txt, template_config.yml, .github/workflows/scripts/install.sh, and .github/workflows/scripts/before_install.sh and submit the changes.

3. Start the "Create New Release Branch" workflow from the master branch in GitHub.

4. Ensure yourself you have configured secrets required for publishing docs/packages as the Pulp user in a Github repository. Start the "Release Pipeline" workflow and specify the tag name that is equal to the milestone specified in the corresponding Redmine project.

## Preparing a Z-release

Releasing a new Z-version of a particular plugin has the same workflow as described above.

## Criteria to have the Y release for plugins

If any of the following is true, release a new Y release of your plugin, otherwise release a Z release.

 * at least one new feature is introduced (it's usually a story or a task in Redmine and it often has .feature changelog file)

 * a floor version bump (Y release) in any dependency

    *  including pulpcore (E.g. it was pulpcore>=3.3 and it becomes pulpcore>=3.9)

 * a django migration which needs to go into a release

# Cherrypicking backports

1. Create a fork of the release branch you want to cherrypick the change to (e.g. `git checkout 3.12 && git checkout -b 3.12-cherrypicks`)

2. Use the cherrypick script to cherry pick the change (e.g. for backport 4567 that backports issue 1234 with commit abcd1234, run `.ci/scripts/cherrypick.sh abcd1234 1234 4567`)

3. Repeat step 2 as many times as necessary if there are multiple backports

4. Push and open a PR against the release branch

Note: some older branches may not have the cherrypick script. It may be necessary to add this script to the release branch:

```

git checkout master -- .ci/scripts/cherrypick.sh

git commit -m "Added cherrypick script [noissue]"  # or git update-index --assume-unchanged .ci/scripts/cherrypick.sh

```