Tutorial: changes in a series
There was a mailing list post [1] walking through developing multiple changes in a series. It was suggested [2] that this content would be suitable for the contributor guide. This patch introduces a new document for that, and also attempts to incorporate some of the other suggestions [3] [4] made in that thread. [1] http://lists.openstack.org/pipermail/openstack-discuss/2018-December/000629.html [2] http://lists.openstack.org/pipermail/openstack-discuss/2018-December/000638.html [3] http://lists.openstack.org/pipermail/openstack-discuss/2018-December/000637.html [4] http://lists.openstack.org/pipermail/openstack-discuss/2018-December/000645.html Change-Id: I2e00505621ba4fec99e98bc1bfb1e37d2468d96d
This commit is contained in:
Eric Fried
parent
24f6e7cab2
commit
7a2205a0c9
|
|
@ -17,6 +17,7 @@ Code & Documentation Contributor Guide
|
|||
/common/git
|
||||
/common/setup-gerrit
|
||||
/code-and-documentation/patch-best-practices
|
||||
/code-and-documentation/patch-series-tutorial
|
||||
/code-and-documentation/devstack
|
||||
/code-and-documentation/using-gerrit
|
||||
/common/zuul-status
|
||||
|
|
|
|||
|
|
@ -111,9 +111,13 @@ A patch chain is easy to handle if you keep in mind a few recommendations:
|
|||
git rebase -i HEAD^
|
||||
|
||||
You need as many '^' as the number of the patch you want to edit first from the
|
||||
top of the chain. Gerrit also provides you options to edit the patch itself or
|
||||
only the commit message and a few more for more advanced changes, like
|
||||
modifying the author.
|
||||
top of the chain. Alternatively you may wish to use `git-restack
|
||||
<https://docs.openstack.org/infra/git-restack/>`_, which figures out the
|
||||
appropriate ``git rebase`` command for you.
|
||||
|
||||
Gerrit also provides you options to edit the patch itself or only the
|
||||
commit message and a few more for more advanced changes, like modifying
|
||||
the author.
|
||||
|
||||
* To download the full chain you need to download the top patch and Git will
|
||||
automatically download all the dependent patches in the chain.
|
||||
|
|
@ -129,6 +133,9 @@ modifying the author.
|
|||
applied the changes in the right one as patches still get merged individually
|
||||
and there is no guarantee that the whole chain gets landed at the same time.
|
||||
|
||||
For a more in-depth look at managing patch chains, see
|
||||
:doc:`/code-and-documentation/patch-series-tutorial`.
|
||||
|
||||
Gerrit Topics
|
||||
-------------
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,223 @@
|
|||
########################################
|
||||
Tutorial: Developing Changes In A Series
|
||||
########################################
|
||||
|
||||
This tutorial walks through a simple scenario of developing multiple change
|
||||
sets in a series on the same branch. If you wish, you can follow along, using
|
||||
the `sandbox repository
|
||||
<http://git.openstack.org/cgit/openstack-dev/sandbox/>`_, executing the
|
||||
commands exactly as they're laid out.
|
||||
|
||||
If you are a visual learner, you may prefer
|
||||
`this video <https://www.youtube.com/watch?v=mHyvP7zp4Ko&list=PLR97FKPZ-mD9XJCfwDE5c-td9lZGIPfS5&index=4>`_
|
||||
which does roughly the same thing (but without ``git-restack``).
|
||||
|
||||
Here we go.
|
||||
|
||||
Start on a freshly-``pull``\ed master branch:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git checkout master
|
||||
Switched to branch 'master'
|
||||
Your branch is up-to-date with 'origin/master'.
|
||||
efried:~/openstack/sandbox$ git pull --all
|
||||
<snip>
|
||||
|
||||
When you're working on a blueprint, you want to name your local branch
|
||||
after the blueprint. For this example, we'll use
|
||||
``bp/nova-cyborg-interaction``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git checkout -b bp/nova-cyborg-interaction
|
||||
Switched to a new branch 'bp/nova-cyborg-interaction'
|
||||
efried:~/openstack/sandbox$ git log --oneline -1 --decorate
|
||||
3d008a3 (HEAD -> bp/nova-cyborg-interaction, origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
|
||||
|
||||
When you ``git commit`` (without ``--amend``), you're creating a new commit on
|
||||
top of whatever commit you started at. If you started with a clean, freshly
|
||||
``pull``\ed master branch, that'll be whatever the most recently merged commit
|
||||
in the master branch was. In this example, that's commit ``3d008a3``.
|
||||
|
||||
So let's say I make an edit for my first patch and commit it:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ echo 'python-cyborgclient>=1.0' >> requirements.txt
|
||||
efried:~/openstack/sandbox$ echo 'python-cyborgclient==1.1' >> lower-constraints.txt
|
||||
efried:~/openstack/sandbox$ git add -A
|
||||
efried:~/openstack/sandbox$ git commit -m "Add cyborg client to requirements"
|
||||
[bp/nova-cyborg-interaction d76195e] Add cyborg client to requirements
|
||||
2 files changed, 2 insertions(+)
|
||||
create mode 100644 lower-constraints.txt
|
||||
efried:~/openstack/sandbox$ git log --oneline -2 --decorate
|
||||
d76195e (HEAD -> bp/nova-cyborg-interaction) Add cyborg client to requirements
|
||||
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
|
||||
|
||||
I just made commit ``d76195e`` on top of ``3d008a3``. You'll notice my branch
|
||||
name (``bp/nova-cyborg-interaction``) came along with me.
|
||||
|
||||
Now I'm going to make another change, but just part of it, a
|
||||
work-in-progress commit:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ mkdir -p nova/pci/cyborg
|
||||
efried:~/openstack/sandbox$ touch nova/pci/cyborg/__init__.py
|
||||
efried:~/openstack/sandbox$ git add nova/pci/cyborg/__init__.py
|
||||
efried:~/openstack/sandbox$ git commit -m "WIP: Cyborg PCI handling"
|
||||
[bp/nova-cyborg-interaction f17f040] WIP: Cyborg PCI handling
|
||||
1 file changed, 0 insertions(+), 0 deletions(-)
|
||||
create mode 100644 nova/pci/cyborg/__init__.py
|
||||
efried:~/openstack/sandbox$ git log --oneline -3 --decorate
|
||||
f17f040 (HEAD -> bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
|
||||
d76195e Add cyborg client to requirements
|
||||
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
|
||||
|
||||
Now commit ``f17f040`` is on top of ``d76195e``, which is still on top of
|
||||
``3d008a3`` (aka ``master``). Note that my branch name came with me again.
|
||||
|
||||
At this point, I push my series up to gerrit. Note that it makes me
|
||||
confirm that I really want to push two commits at once.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git review
|
||||
You are about to submit multiple commits. This is expected if you are
|
||||
submitting a commit that is dependent on one or more in-review
|
||||
commits, or if you are submitting multiple self-contained but
|
||||
dependent changes. Otherwise you should consider squashing your
|
||||
changes into one commit before submitting (for indivisible changes) or
|
||||
submitting from separate branches (for independent changes).
|
||||
|
||||
The outstanding commits are:
|
||||
|
||||
f17f040 (HEAD -> bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
|
||||
d76195e Add cyborg client to requirements
|
||||
|
||||
Do you really want to submit the above commits?
|
||||
Type 'yes' to confirm, other to cancel: yes
|
||||
remote:
|
||||
remote: Processing changes: new: 2, refs: 2
|
||||
remote: Processing changes: new: 2, refs: 2
|
||||
remote: Processing changes: new: 2, refs: 2, done
|
||||
remote:
|
||||
remote: New Changes:
|
||||
remote: https://review.openstack.org/635341 Add cyborg client to requirements
|
||||
remote: https://review.openstack.org/635342 WIP: Cyborg PCI handling
|
||||
remote:
|
||||
To ssh://review.openstack.org:29418/openstack-dev/sandbox.git
|
||||
* [new branch] HEAD -> refs/for/master%topic=bp/nova-cyborg-interaction
|
||||
|
||||
Now if you go to either of those links - e.g.
|
||||
https://review.openstack.org/#/c/635342/ - you'll see that the patches
|
||||
are stacked up in series on the top right.
|
||||
|
||||
But oops, I made a mistake in my first commit. My lower constraint can't be
|
||||
higher than my minimum in ``requirements.txt``. If I still had my branch
|
||||
locally, I could skip this next step, but as a matter of rigor to avoid some
|
||||
common pratfalls, I will pull the whole series afresh from gerrit by asking
|
||||
``git-review`` to grab the *top* change:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git review -d 635342
|
||||
Downloading refs/changes/42/635342/1 from gerrit
|
||||
Switched to branch "review/eric_fried/bp/nova-cyborg-interaction"
|
||||
|
||||
Now I'm sitting on the top change (which you'll notice happens to be
|
||||
exactly the same as before I pushed it - again, meaning I could
|
||||
technically have just worked from where I was, but see above):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git log --oneline -3 --decorate
|
||||
f17f040 (HEAD -> review/eric_fried/bp/nova-cyborg-interaction, bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
|
||||
d76195e Add cyborg client to requirements
|
||||
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
|
||||
|
||||
But I want to edit ``d76195e``, while leaving ``f17f040`` properly stacked on
|
||||
top of it. Here I use a tool called `git-restack
|
||||
<https://docs.openstack.org/infra/git-restack/>`_ (run ``pip install
|
||||
git-restack`` to install it).
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git restack
|
||||
|
||||
This pops me into an editor showing me all the commits between wherever
|
||||
I am and the main branch (now they're in top-first order):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pick d76195e Add cyborg client to requirements
|
||||
pick f17f040 WIP: Cyborg PCI handling
|
||||
<snip>
|
||||
|
||||
I want to fix the first one, so I change ``pick`` to ``edit``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
edit d76195e Add cyborg client to requirements
|
||||
pick f17f040 WIP: Cyborg PCI handling
|
||||
<snip>
|
||||
|
||||
Save and quit the editor, and I see:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
Stopped at d76195e... Add cyborg client to requirements
|
||||
You can amend the commit now, with
|
||||
|
||||
git commit --amend
|
||||
|
||||
Once you are satisfied with your changes, run
|
||||
|
||||
git rebase --continue
|
||||
|
||||
I fix ``lower-constraints.txt``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ sed -i 's/cyborgclient==1.1/cyborgclient==1.0/' lower-constraints.txt
|
||||
|
||||
...and *amend* the current commit
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git commit -a --amend --no-edit
|
||||
[detached HEAD df226f7] Add cyborg client to requirements
|
||||
Date: Wed Feb 6 16:15:30 2019 -0600
|
||||
2 files changed, 2 insertions(+)
|
||||
create mode 100644 lower-constraints.txt
|
||||
|
||||
...and tell ``git-restack`` to proceed
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git rebase --continue
|
||||
Successfully rebased and updated refs/heads/review/eric_fried/bp/nova-cyborg-interaction.
|
||||
|
||||
If I had a taller series, and I had changed ``pick`` to ``edit`` for more than
|
||||
one commit, I would now be sitting on the next one I needed to edit. As it is,
|
||||
that was the only thing I needed to do, so I'm done and sitting on the top of
|
||||
my series again.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
efried:~/openstack/sandbox$ git log --oneline -3 --decorate
|
||||
e937eef (HEAD -> review/eric_fried/bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
|
||||
df226f7 Add cyborg client to requirements
|
||||
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
|
||||
|
||||
Notice that the commit hashes have changed for *both* commits (but not
|
||||
for ``master``). The top one changed because it got rebased onto the new
|
||||
version of the middle one.
|
||||
|
||||
Now if I push the series back up to gerrit, I get the same confirmation
|
||||
prompt, and both changes get a new patch set. If you look at the top
|
||||
patch in gerrit, you'll see that patch set 2 shows up as just a rebase.
|
||||
|
||||
.. :: TODO: Describe gotchas when restacking and the automatic rebase results in
|
||||
merge conflicts.
|
||||
Loading…
Reference in New Issue