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, executing the commands exactly as they’re laid out.

If you are a visual learner, you may prefer this video which does roughly the same thing (but without git-restack).

Here we go.

Start on a freshly-pulled master branch:

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.

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 pulled 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:

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:

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.

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.opendev.org/635341 Add cyborg client to requirements
remote:   https://review.opendev.org/635342 WIP: Cyborg PCI handling
remote:
To ssh://review.opendev.org:29418/opendev/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.opendev.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:

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):

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 (run pip install git-restack to install it).

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):

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:

edit d76195e Add cyborg client to requirements
pick f17f040 WIP: Cyborg PCI handling
<snip>

Save and quit the editor, and I see:

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:

efried:~/openstack/sandbox$ sed -i 's/cyborgclient==1.1/cyborgclient==1.0/' lower-constraints.txt

…and amend the current commit

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

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.

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.

Tutorial: Developing Changes In A Series

Tutorial: Developing Changes In A Series¶

contributor-guide