Pulp3 Release Guide

This serves as a step-by-step guide to implement a Pulp 3 release.

Releasing Pulpcore

Releases always happen on the X.Y branch. The release itself is a tagged commit.

1. Build the changelog with the towncrier --version x.y.z --draft command. If it looks good rebuild with towncrier --version x.y.z. This will stage git changes for you.

2. Commit the changelog by itself. (first commit)

3. Increment the versions in setup.py and pulpcore/__init__.py to the release versions. e.g. 3.0.1

4. Commit the version bump (second commit). Note the hash of this commit.

5. Increment the versions in setup.py and pulpcore/__init__.py to the next, unreleased version for that branch. For a y-release of 3.1.0 on 'master' would be 3.2.0.dev. For a z-release 3.0.1 on the 3.0 branch, the next unreleased version would be 3.0.2.dev. If you're making a new y-release, also bump the value for stable_branch in template_config.yml.

6. Commit the version bump (third commit).

7. Make a PR and merge it.

8. Make a tag of the "second commit" from above. That one has the changelog and a correct version number. Tag it with e.g. git tag 3.0.1 9fceb02

9. Push the tag with git push origin 3.0.1.

10. Create the github release from the tag. After the PR is merged, go to https://github.com/pulp/pulpcore/releases/new to create a new release from the existing tag.

11. Creating a new tag starts a Travis job that pushes the package to PyPI. Go to https://travis-ci.com/pulp/pulpcore/builds and monitor the job. After the job is done, validate that the new package is on PyPI.

12. Create a pulpcore (Not Shared) Sprint/Milestone with the name of the release, e.g. 3.0.1. You can do this here Then do these Redmine steps below. To make this easier, I take the issue IDs and for a query like this: https://pulp.plan.io/issues?set_filter=1&status_id=*&issue_id=5707,5894,5896,5941,5955,5955,5833,5867,5870,5873,5706,5941

13. Announce to pulp-dev@redhat.com with a summary of all the changes.

14. If making a z-stream release, cherry pick the change log (second commit) to the 'master' branch such as git cherry-pick -x 420dd1ff2f326db454b216f33d848d5267489dfb and merge it to master via a PR

15. If making a y-stream release, create branch and push branch from the tag. See docs on this step in the section below.

Preparing a Y-release

If you are creating a y-stream release, e.g. 3.1.0, you'll need to perform branching. If making a z-stream release you don't need to do this section because you already have a branch to work on.:

1. Update the supported-releases.json file here to the 3.y version in a PR like this one. 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.

2. Create the new X.Y branch from a clean checkout of the y-release tag. For example to make the 3.1 branch from 3.1.0 we ran:

git fetch pulp    # assumes the remote 'pulp' is https://github.com/pulp/pulpcore
git checkout 3.1.0    # This is the tag you're branching from
git reset --hard 3.1.0
git checkout -b 3.1
git push pulp 3.1

3. Increment the versions in setup.py, docs/conf.py, and pulpcore/__init__.py to the next z-release. So if you are making 3.0.0, the 3.1 branch would become 3.0.1.dev.

4. Commit the version bump to the 3.y branch you created

5. Update the stable_branch variable in template_config.yml and set it to the branch you just created (eg "3.1"). This is used to determine the latest stable branch when for example the cherry pick processor needs to cherry pick commits.

Cherry Picking Process

For pulpcore, Travis has a cron job that runs and checks merged PRs for the 'Needs Cherry Pick' label. Any PR that has that label will be cherry picked and included on a PR which is then tested per the usual process. A human merged that final PR and the label is removed.

Other plugins can opt in to using the plugin_template "cherry_pick_automation" variable. See the plugin_template docs for more infomartion on opting in to this CI/CD feature.

Releasing a Plugin

Releasing a plugin has the same process as described above except it happens on the plugin repo instead of https://github.com/pulp/pulpcore