Skip to content

Porting PRs between Kata 1.x and Kata 2.0

Jump to bottom Edit New page
James O. D. Hunt edited this page Sep 7, 2020 · 6 revisions

Background

Historically, each Kata component was developed in its own repository (runtime, agent, et cetera).

However, for Kata 2.0 we are consolidating the components over time into the main kata-containers repository.

Components in multiple repositories

At the time of writing:

  • The branch used for 2.0 development is 2.0-dev.
  • The following components have been copied into the 2.0 branch (with the exception of the agent, which is a new codebase).
Component 1.x location 2.0 location Copy PRs
agent agent 1.x (golang) agent 2.0 (rust) n/a - new code
documentation documentation 1.x documentation 2.0 https://github.com/kata-containers/kata-containers/pull/330
osbuilder osbuilder 1.x osbuilder 2.0 https://github.com/kata-containers/kata-containers/pull/204
packaging packaging 1.x packaging 2.0 Copied
runtime runtime 1.x runtime 2.0 https://github.com/kata-containers/kata-containers/pull/352
https://github.com/kata-containers/kata-containers/pull/353
https://github.com/kata-containers/kata-containers/pull/362

Porting

Since we need to maintain the 1.x branches and the 2.0 repository, we sometimes need to "double fix" in the repostories above: potentially every bug fix PR raised in one of the 1.x repositories listed above also needs to be raised to update the 2.0 copy.

  • If you raise a PR in a 1.x repository listed above that should also be applied to the 2.0 repository, you need to forward port the PR to the 2.0 repository.
  • If you raise a PR in the 2.0 repository that should also be applied in a 1.x repository, you need to backport the PR to the appropriate 1.x repository.

What should be ported?

  • Features: Since the main focus of Kata development is now 2.0, new features should be raised in the 2.0 repository initially. The community will decide if it makes sense to backport these to Kata 1.x.
  • Bug fixes: These should be fixed in both 1.x and 2.0.

When to port?

Please port to the "other" repository as soon as possible. This increases the likelihood that your PR will apply cleanly (no conflicts).

Which direction to port in?

Should you raise a PR in the 1.x repository first, or the 2.0 repository? It depends, but generally:

  • Features: These should be raised in the 2.0 repository first (these may not even need to be backported).
  • Bug fixes: These can either be applied to 1.x first or 2.0 first. Consider how important the fix is; at the time of writing 2.0 has not been released so it may make sense to raise the bug fix on 1.x first since this has a larger user base.

How to port?

Create a new issue

As soon as you raise a PR, consider raising an issue in the "other" repository. Add a link to the original issue and the original PR to this issue and ideally assign it to yourself.

For example,

  • If you raise a PR in the 1.x repository, raise a porting issue in the 2.0 repository.
  • If you raise a PR in the 2.0 repository, raise a porting issue in the appropriate 1.x repository.

Apply the code to the "other" repository

Here is an example of "forward porting" from the 1.x runtime repository to the 2.0 repository:

Create the 1.x PR

$ cd $GOPATH/src/github.com/kata-containers/runtime
$ git co -b my-awesome-fix
$ << change files >>
$ git commit -as
$ git push

Create the 2.0 PR

First, fork https://github.com/kata-containers/kata-containers to create your own clone. Then:

$ git clone <your_fork_URL> # e.g. https://github.com/<your_github_account_name>/kata-containers
$ cd kata-containers
$ repo="runtime"
$ branch="my-awesome-fix"
$ git checkout -b "$branch"
# some ${repo}s are in tools/, not src/, in which case you'll need --directory=tools/$repo in the following command line
$ (cd $GOPATH/src/github.com/kata-containers/$repo && git checkout "$branch" && git format-patch --stdout master..) | git am --patch-format=stgit --directory=src/$repo
$ git rebase -i 2.0-dev
<< Rework the commit message(s) to reference the 2.0 issue number in the "Fixes:" comment, etc >>
$ git push

Then create a pull request using the URL indicated by git push output.

Notes:

  • The 1.x runtime code is stored at the top-level of the runtime repository in the master branch.
  • The 2.0 runtime code is stored in the src/runtime/ sub-directory of the kata-containers repository in the 2.0-dev branch.
  • The --directory= option to git am ensures the patch applies to the correct sub-directory of the 2.0 repo.
  • This example assumes the code will actually apply. If it doesn't git checkout -f in the destination branch / repository to reset it to a pristine state. Then you could use git format-patch to export the PR patch set from the source branch / repository and then apply each patch in sequence to the destination repository, fixing up problems as you go, and finally creating a PR from the new patch set in the destination branch / repository. Please always ensure you reference the source issue number and ideally also the source PR URL in your new PR in the destination branch / repository. If the new PR is in a different repository, you will need a new issue for the Fixes: ### comment, and in that scenario reference the source issue URL in one of your commits.

See also

Add a custom footer
Add a custom sidebar
Clone this wiki locally