Wireshark · Wireshark-dev: [Wireshark-dev] Quick start instructions for Gerrit

[Marc Petit-Huguenin <marc@xxxxxxxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Thess quick start instructions assume that you know about git, that you
already have an ssh key pair configured and that ssh and git are installed on
your computer.  Note that the email configured in git must match the email
that you used in the Gerrit configuration.

First step is to clone the Wireshark repository, which need to be done only
one time:

- - Start by creating a new account in Gerrit by going to the
http://test.code.wireshark.org/review/ page, and clicking of the Register
link, on the top right.

- - Here the simplest is to use an existing Google or Yahoo ID.  Just follow the
instructions until you are back on the test.code.wireshark.org site.

- - On the page, choose a username and save it.  Copy the content of your ssh
public key (~/.ssh/id_rsa.pub) and add it, then click continue.  You are done
for now with the web interface.

- - Go to your command line and enter the following command (replacing
<username> by the user name you entered in the web page):

git clone ssh://<username>@test.code.wireshark.org:29418/wireshark-review-sandbox

- - After it is done (it will take a minute of so), install the change-id hook
with the following commands:

cd wireshark-review-sandbox
scp -p -P 29418 <username>@test.code.wireshark.org:hooks/commit-msg .git/hooks/

- - Finally install a shortcut to push patchsets:

git config --add remote.origin.push HEAD:refs/for/master


After this, you can prepare your first patchset.  One of the essential rule is
that you *never*, *ever* work in the master branch.  This branch must be
considered read-only.  So to create a patchset, you need first to create a
topic branch.  I personally always name a topic branch so it ends with the
name of the branch onto which the patchset will be merged, so in this case,
- -master:

git checkout -b first-patchset-master

This will create a new branch (from the tip of the master branch) and switch
to it (you can list your branches with "git branch")

Now you can do all your modifications.  When you are done, you need to commit
them.  The simplest is this command:

git commit -a

Note that git will ask you for a commit message, which is as important as the
modified code itself.  The usage if to have a title of no more than 50
characters, an empty line, then an explanation on the commit itself.

After the modifications are committed you can review the commit with "git log
- -p".  Note that a field name "Change-ID" was automatically added.  This is the
magic that will glue multiple revisions of the same patchset, do not modify
it.  If everything looks fine, you can push it with the following command:

git push

And that's it, congratulations, your first patchset is ready for review, and
you can see it on the website, by clicking on My|Changes.

Obviously some patchsets will probably be merged in the master branch before
your patchset is reviewed and merged, so you will need to rebase it.  First to
need to switch back to the master branch and to pull all the new modifications:

git checkout master
git pull

If you followed the rule above (never work on the master branch), there should
not be any conflicts when running the "git pull" command.  The next step is to
rebase your patchset:

git rebase master first-patchset-master

There may be conflicts at this time.  Resolve them, do a "git add" of the
modified files and then finish the rebase with the following command with the
following command:

git rebase --continue

(you may have to do that multiple times)

It may be a good time to do the modifications that were requested by your
reviewers:  apply then then amend the existing commit (do not add a new
commit, you want a clean history, not a catalog of your mistakes):

git commit --amend -a

Then push again your patchset:

git push

The new patchset will appear on the web page in parallel to the previous
patchset, where it can be reviewed again and eventually merged into master.

After your patchset is merged into master, do a pull and a rebase again of
your (now useless) branch.  If everything went well, you should be able to
safely delete the topic branch with this command (the branch will not be
deleted if it was not completely merged):

git checkout master
git branch -d first-patchset-master

Enjoy!

- -- 
Marc Petit-Huguenin
Email: marc@xxxxxxxxxxxxxxxxxx
Blog: http://blog.marc.petit-huguenin.org
Profile: http://www.linkedin.com/in/petithug
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.14 (GNU/Linux)

iQIcBAEBCAAGBQJSOkqwAAoJECnERZXWan7Esd8P/RR5ePQhNcXZyMbj3A0iSlhl
iyDI3nu+qTb7MTUbpL3BUD5KI+k6BeCUFfN6kimx8YNIGe/mmU6gJKMqMjvA3RZs
3L2v2FFFzMnCeeJQbRrGvAb6/whYb8AiCWvtw0/lVwVYAlG7QxB8Uo3wxXpwjLAk
x5aneQ6ZCHmWYtmwliIGz4Y9opNerDoSlXfNaJpI+dqPLr3vqj3/nkLQ6iqTzeVq
ioSZo6X4ddSnfSwe9V6U8AyP4moJd81nq/EKFl9/i+CYfXf56iHaClf3a/YC8eq/
lfgPHcpp0LYjPzRXkvNqLfHRPoYFm/79ErYW5G/JKPPjmZ1hRo2Ht6Z4L0NXHhUZ
HPekDpq/g/pdJFl+zsMRwXwUQcyqxaf7UqqerzSdHqEEFOKgU1rl4Og0e7VDC2TA
R0fPOAa4QKj+rKWzF8hZEKkWuhN6+g2yWmV/oqF/uEh4XXfT7s12DU6J8Nhh2lwx
kDUIGGVgjtij6LDjrHRbdjakgDrT+MI9J8p67J4v2iiomWjpq265xJdrqHJ8FfAR
9klaOII1+WQW8L5sJG464/ExQkaBwJmT97eX1Hh+SPntBfoz4WpucSNwko1SDtzG
bRvVL7sN0KbAxeI8/2SY8nKsCScC3MyRzh0yHlRgQy1MpDSAgClwyuF8TFgWrWls
/iY+bQHSyKE3JA4NR3j6
=UtTD
-----END PGP SIGNATURE-----