How to Create a Change

Skip to end of metadata
Go to start of metadata
Be Careful
The information in this article is beta-quality and has not been fully tested in practice yet. Feel free to report any discrepancies by commenting below the article.

Before you begin

Before starting to change the code, please follow the Checking Out Code for Development article. After this is done, making a change is a simple 5-step process:

Unknown macro: {gliffy}

Let's have a look at these steps. There is also an example at the end.

1. A programmer fixes his imagination in a tangible form called a hack*

Let's say you have found some bug in our code you think you can fix, or picked up some nice ticket on our JIRA issues list. In other words, you want to make a change in SIO2. If you haven't contributed to any open source project before, you may find yourself a bit confused. This tutorial will help you get started in developing SIO2.

If you want to start from an easy task, and would like to have your code in SIO2 soon, try the inspirations page.

2. The programmer gets some pizza, enters the cleanroom and hacks.

Hacking should be started from a clean and up-to-date repository state, for example by creating a new branch from origin/master:

$ git fetch
$ git checkout -b my_new_hack origin/master

Then the programmer hacks until he thinks the hack is good enough that no reviewer will think that this is a hack, but everyone will see the beauty of a clean solution.

Do not place two independent changes in a single Git commit.
There are some tricks you should know:
  • If your change adds or modifies fields or classes which are stored in the database, reading the Using Database Migrations article is a must.

3. The programmer writes tests for the code.

We have a separate article on how to write, run, debug, fix, run again, fix again, and celebrate the tests in SIO2.

4. The programmer sends his change for review.

The programmer should commit the change locally, adding a meaningful description, not forgetting to place the ID of the Jira issue, if any.

$ git add ...
$ git rm ...
$ git commit

If there is a ticket no XXX connected with the commit the commit message should look like:

SIO-XXX Short description

Longer description which can be:
- multi-line
- have bullet-points if you want
- etc.

Otherwise you should start your message with (no-ticket).

The short description should be in imperative mood, eg. "Fix exception in fooinator".

Then the change should be admired by its author. After going into admiration of his own change, the programmer wants others to admire it as well. Artists use galleries for this, programmers use Gerrit.

The process looks like this:

  • the programmer sends the change using
    $ git push origin HEAD:refs/for/master
    It's wise to alias this command to git review in .gitconfig — see Checking Out Code for Development

    This sends all the local commits which are not in origin/master to Gerrit. Each commit creates a separate Gerrit change.

  • the programmer may open each of the created Gerrit changes to assign specific reviewers through the web interface (URLs of newly created changes are printed by git review). The programmer may add reviewers manually or wait for someone from the SIO2 team to assign them.

After the changes are uploaded to Gerrit, the tests will be automatically run for each of them. If any of the tests fail, the change bust be fixed (see the next section).

In order to submit the change to the main repository, the change must meet the requirements listed below.

    • a Verification OK status from our automatic tester — Hudson,
    • Looks Good To Me from all assigned reviewers.
If there is a Jira issue for a given change, put its number somewhere in the change description.

5. The programmer sees a review.

If the programmer disagrees with reviewer's comments, they should discuss the issue on Gerrit (using Review with no score) or in person, on Jabber, by e-mail, etc. If there are problems with going into agreement, write to

Often the Gerrit change needs to be updated. This is done by uploading additional patch sets. You do this by "changing" the Git commit in your local repository, but retaining the original Change-Id: line, which is added automatically to all Git commit messages.

So for example, assuming that your branch was named my_new_hack, you should do something like this:

$ git fetch
$ git checkout my_new_hack
$ git rebase origin/master
$ # some hacking
$ git add ...
$ git rm ...
$ git commit --amend
$ git push origin HEAD:refs/for/master

Please do not change the Change-Id line in the change description. If there is no Change-Id line, go back to Checking Out Code for Development and make sure that appropriate Git hooks are installed.

After this, the change in Gerrit should show a new patch set, which again should be reviewed by the reviewer. Automatic e-mail message is sent to all reviewers as well.

If you don't have your branch, or don't know which one is that one, copy the command directly from Gerrit. It should look like

$ git fetch ssh:// refs/changes/52/552/2 && git checkout FETCH_HEAD

6. The programmer wants his change submitted to the repository.

There are two cases here:

  1. If the developer is a distinguished contributor and blongs to the sio2-developers group in our accounts system, it's his job to click Submit Patch Set # in Gerrit.
  2. Otherwise the last reviewer who adds Looks Good to Me shoult attempt to submit.

If Gerrit says "Cannot merge due to conflicts", this means that some conflicting changes were accepted while the change was under review. The author must rebase the change to the current origin/master, resolving eventual conflicts.

$ git fetch
$ git checkout my_new_hack
$ git rebase origin/master
$ git push origin HEAD:refs/for/master
While rebasing, you may have to manually resolve some conflicts. Type git status to check the files causing conflicts. After resolving them, type git rebase --continue

After the change is submitted, if there is a Jira issue for the change, the programmer resolves the Jira issue.

The programmer may resolve the Jira issue directly from Gerrit, by adding a review comment with #RESOLVE string in it.
Please do it only after the issue is submitted to the main repository.

The programmer may now delete the local Git branch.

6. The programmer parties.

... because the newly created change will automatically appear in the day's nightly builds.

Final notes

It might be a good idea to develop a habit of running git status every time you start making changes, to make sure that you are working in an intended branch.


TODO: This example should have writing unittests.
TODO: This example should demonstrate rebasing and resolving conflicts.

Let's say you have found a bug in src/sio2/web/templates/ingredients/default_menu.html.

Unknown macro: {code}
Unknown macro: {% if request.identiy %}

<!-- should be identity -->
<a href="{{ tg.url('c_reg_edit', login=userid) }}">{{ _("Registration data") }}</a>

Unknown macro: {% endif %}

Suppose you already have the code. Create new git branch for this fix: (In such small changes you may want to fix the error directly in your master branch, but it's safer to always create separate one)

Unknown macro: {code}

git fetch
git checkout -b bug_fix origin/master

Now just edit the file and correct the spelling mistake.
Assuming you are in the src/sio2/web/templates/ingredients/ directory, type:

Unknown macro: {code}

git add default_menu.html
git commit

The last command will open default git editor, and you will have to type commit message on top of the file:

Now all you need to do is

Unknown macro: {code}

git push origin HEAD:refs/for/master

Your change will now be reviewed in Gerrit. Go to the changeset page, wait for Hudson verification and if it's ok, add reviewers (or wait for someone to add them):

Click on Side-by-Side to view the diff of the file:

If all the reviewers accepted your change, and it passed the unittests, you can submit your change. If there are no conflicts you should now see:

You have helped SIO2 on it's path to greatness!!!

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.