Backporting process¶

Backport Criteria¶

Committers may nominate PRs that have been merged into master as candidates for backport into stable_releases if they affect the stable production usage of community users.

Backport criteria for current minor release¶

Criteria for inclusion into the next stable release of the current latest minor version of Cilium, for example in a v1.2.z release prior to the release of version v1.3.0:

All bugfixes

Backport criteria for X.Y-1.Z and X.Y-2.Z¶

Criteria for the inclusion into the next stable release of the prior two minor versions of Cilium, for example in a v1.0.z or v1.1.z release prior to the release of version v1.3.0:

Security relevant fixes
Major bugfixes relevant to the correct operation of Cilium

Backporting guide¶

Cilium PRs that are marked with the label needs-backport/X.Y need to be backported to the stable branch X.Y. The following steps summarize the process for backporting these PRs:

One-time setup
Preparing PRs for backport
Cherry-picking commits into a backport branch
Posting the PR and updating GitHub labels

One-time setup¶

The scripts referred to below need to be run in Linux, they do not work on OSX. You can use the cilium dev VM for this, but you need to configure git to have your name and email address to be used in the commit messages:
```
$ git config --global user.name "John Doe"
$ git config --global user.email [email protected]
```
Make sure you have your a GitHub developer access token available. For details, see contrib/backporting/README.md

This guide makes use of several tools to automate the backporting process. The basics require bash and git, but to automate interactions with github, further tools are required.

Dependency	Required?	Download Command
bash	Yes	N/A (OS-specific)
git	Yes	N/A (OS-specific)
python3	No	Python Downloads
PyGithub	No	`pip3 install PyGithub`
Github command-line tools	No	`npm install -g gh`

Preparation¶

Pull requests that are candidates for backports to the X.Y stable release are tracked through the following links:

PRs with the needs-backport/X.Y label (1.7: GitHub Link)
PRs with the backport-pending/X.Y label (1.7: GitHub Link)
The X.Y GitHub project (1.7: GitHub Link)

Make sure that the Github labels are up-to-date, as this process will deal with all commits from PRs that have the needs-backport/X.Y label set (for a stable release version X.Y). If any PRs contain labels such as backport-pending/X.Y, ensure that the backport for that PR have been merged and if so, change the label to backport-done/X.Y.

Creating the backports branch¶

Run contrib/backporting/start-backport for the release version that you intend to backport PRs for. This will pull the latest repository commits from the Cilium repository (assumed to be the git remote origin), create a new branch, and runs the contrib/backporting/check-stable script to fetch the full set of PRs to backport.
```
$ GITHUB_TOKEN=xxx contrib/backporting/start-backport 1.0
```
Note

This command will leave behind a file in the current directory with a name based upon the current date in the form YYYY-MM-DD.txt which contains a prepared backport pull-request description so you don’t need to write one yourself.
Cherry-pick the commits using the master git SHAs listed, starting from the oldest (top), working your way down and fixing any merge conflicts as they appear. Note that for PRs that have multiple commits you will want to check that you are cherry-picking oldest commits first. The cherry-pick script accepts multiple arguments, in which case it will attempt to apply each commit in the order specified on the command line until one cherry pick fails or every commit is cherry-picked.
```
$ contrib/backporting/cherry-pick <oldest-commit-sha>
...
$ contrib/backporting/cherry-pick <newest-commit-sha>
```
(Optional) If there are any commits or pull requests that are tricky or time-consuming to backport, consider reaching out for help on Slack. If the commit does not cherry-pick cleanly, please mention the necessary changes in the pull request description in the next section.
Push your backports branch to cilium repo.
```
$ git push -u origin
```

Creating the backport pull request¶

The backport pull-request may be created via the GitHub web interface, or alternatively you can use CLI tools to achieve these steps.

Via GitHub web interface¶

Create a new PR from your branch towards the feature branch you are backporting to. Note that by default Github creates PRs against the master branch, so you will need to change it. The description for the pull request should be based upon the YYYY-MM-DD.txt file that was generated by the scripts above.
Label the new backport PR with the backport label for the stable branch such as backport/X.Y as well as kind/backports so that it is easy to find backport PRs later.
Mark all PRs you backported with the backport pending label backport-pending/X.Y and clear the needs-backport/vX.Y label.

Via command-line tools¶

These steps require all of the tools described in the One-time setup section above. Note that the list of PRs to pass to the set-labels.py script are listed at the end of the YYYY-MM-DD.txt file.

# Create a pull-request on Github
$ gh pull-request -b vX.Y -l backport/vX.Y -F YYYY-MM-DD.txt
# Set PR 1234's v1.0 backporting labels to pending
$ contrib/backporting/set-labels.py 1234 pending 1.0

After the backports are merged¶

After the backport PR is merged, mark all backported PRs with backport-done/X.Y label and clear the backport-pending/X.Y label(s). If the backport pull request description was generated using the scripts above, then the full command is listed in the pull request description.

# Set PR 1234's v1.0 backporting labels to done
contrib/backporting/set-labels.py 1234 done 1.0.