79 lines
3.8 KiB
ReStructuredText
79 lines
3.8 KiB
ReStructuredText
=================
|
|
Backporting a Fix
|
|
=================
|
|
|
|
From time to time, you may find a bug that's been fixed in master, and you'd
|
|
like to have that fix in the release you're currently using (for example,
|
|
Wallaby). What you want to do is propose a **backport** of the fix.
|
|
|
|
.. note::
|
|
The Skyline Console project observes the OpenStack `Stable Branch Policy
|
|
<https://docs.openstack.org/project-team-guide/stable-branches.html>`_.
|
|
Thus, not every change in master is backportable to the stable branches.
|
|
In particular, features are *never* backportable. A really complicated
|
|
bugfix may not be backportable if what it fixes is low-occurrence and
|
|
there's a high risk that it may cause a regression elsewhere in the
|
|
software.
|
|
|
|
How can you tell? Ask in the ``#openstack-skyline`` channel on IRC.
|
|
|
|
Since we use git for source code version control, backporting is done by
|
|
*cherry-picking* a change that has already been merged into one branch into
|
|
another branch. The gerrit web interface makes it really easy to do this.
|
|
In fact, maybe *too* easy. Here are some guidelines:
|
|
|
|
* Before you cherry-pick a change, make sure it has already **merged**
|
|
to master. If the change hasn't merged yet, it may require further
|
|
revision, and the commit you've cherry-picked won't be the correct
|
|
commit to backport.
|
|
|
|
* Backports must be done in *reverse chronological order*. Since
|
|
OpenStack releases are named alphabetically, this means reverse
|
|
alphabetical order: ``stable/yoga``, ``stable/xena``, etc.
|
|
|
|
* The cherry-pick must have **merged** into the closest most recent branch
|
|
before it will be considered for a branch, that is, a cherry-pick to
|
|
``stable/xena`` will **not** be considered until it has merged into
|
|
``stable/yoga`` first.
|
|
|
|
* This is because sometimes a backport requires revision along the
|
|
way. For example, different OpenStack releases support different
|
|
versions of Python. So if a fix uses a language feature introduced
|
|
in Python 3.8, it will merge just fine into current master (during zed
|
|
development), but it will not pass unit tests in ``stable/yoga``
|
|
(which supports Python 3.6). Likewise, if you already cherry-picked
|
|
the patch from master directly to ``stable/xena``, it won't pass tests
|
|
there either (because xena also supports Python 3.6).
|
|
|
|
So it's better to follow the policy and wait until the patch is merged
|
|
into ``stable/yoga`` *before* you propose a backport to ``stable/xena``.
|
|
|
|
* You can propose backports directly from git instead of using the gerrit
|
|
web interface, but if you do, you must include the fact that it's a
|
|
cherry-pick in the commit message. Gerrit does this automatically for
|
|
you *if you cherry-pick from a merged commit* (which is the only kind of
|
|
commit you should cherry-pick from in Gerrit); git will do it for you if
|
|
you use the ``-x`` flag when you do a manual cherry-pick.
|
|
|
|
This will keep the history of this backport intact as it goes from
|
|
branch to branch. We want this information to be in the commit message
|
|
and to be accurate, because if the fix causes a regression (which is
|
|
always possible), it will be helpful to the poor sucker who has to fix
|
|
it to know where this code came from without digging through a bunch of
|
|
git history.
|
|
|
|
If you have questions about any of this, or if you have a bug to fix that
|
|
is only present in one of the stable branches, ask for advice in
|
|
``#openstack-skyline`` on IRC.
|
|
|
|
Backport CI Testing
|
|
-------------------
|
|
|
|
Like all code changes, backports should undergo continuous integration
|
|
testing. This is done automatically by Zuul for changes that affect the
|
|
main skyline-console code.
|
|
|
|
This shouldn't be a big deal because presumably you've done local
|
|
testing with your backend to ensure that the code works as expected in a
|
|
stable branch; we're simply asking that this be documented on the backport.
|