Update: a good chunk of this page is deprecated and has been superseded by the GitLab workflow.

GNOME development process is based on developers attaching patches to bugs in Bugzilla and other developers and UI designers reviewing the content and functionality of these patches.

How to set up Git

Your patches will need to have your name and e-mail in them. Here is how you set up Git with this information:

  git config --global user.name "Your Name"
  git config --global user.email your.email@domain.com

You will also find the following setting useful for detecting trailing whitespaces. It color-codes the output of git commands like git diff and git show.

  git config --global color.diff auto

How to make a patch

The first thing you need to do is to commit your changes in your local repository, as we prefer reviewing formatted patches rather than diffs. git commit -a allows you to commit a patch locally. Please follow the guidelines outlined in this e-mail when creating a commit message.

You can use git format-patch to create a file with a patch if you need to share it in some way other than Bugzilla or if you want to attach it in Bugzilla by hand. git format-patch HEAD^ will create a formatted patch file for the last commit you made locally.

How to attach a patch to a bug in Bugzilla

git-bz is a tool that allows you to attach patches to bugs in Bugzilla with a single command line. It's much nicer than the alternative of attaching a patch by hand. To install git-bz, you can either download the script

  curl http://git.fishsoup.net/cgit/git-bz/plain/git-bz > ~/bin/git-bz
  chmod a+x ~/bin/git-bz

or the full check out.

  cd ~
  git clone git://git.fishsoup.net/git-bz
  cd ~/bin/
  ln -s ~/git-bz/git-bz .

You can then attach the last patch you committed locally to a bug nnnnnn by running git bz attach nnnnnn HEAD See the git-bz manual page for all the usage options.

When there's no fitting bug, you can use git bz file gnome-shell/general HEAD to create a new bug containing your patch. The "gnome-shell/general" specifies the product and component: "mutter/general", "gnome-shell/calendar" and any valid combination on Bugzilla will work.

You can add a "ui-review" keyword to the bug if you want a UI designer to review the functionality of your patch. Some bugs will already have this keyword if the UI designers have previously taken interest in them.

How to review a patch

Git patches have a "review" link next to them in Bugzilla. This review mode is enabled by Splinter. It shows the diff for all the affected files and allows inline commenting by double-clicking on the lines you want to comment on. Once you are done, you need to assign a status to the patch, such as "accepted_commit_now", "reviewed", or "needs_work", and publish your review. "accepted_commit_now" status is used when the patch can pretty much be committed as is, "reviewed" status is used when there are some minor straight-forward changes that need to be made to the patch, and "needs_work" means that the patch requires substantial changes and the new patch should be attached for a review later. It's up to the discretion of the patch author to decide if a patch that was marked as "reviewed" requires a subsequent review.

Just clicking on the main attachment link will show you the raw patch.

How to apply a patch from a bug in Bugzilla

git bz apply nnnnnn will offer you to apply each current patch attached to the bug nnnnnn. See the git-bz manual page for all the usage options.

You can apply a patch that was earlier formatted with git format-patch and that you have saved as a local file new_patch.patch by running git am new_patch.patch

When a patch can be pushed

A patch can be pushed to the main repository when it has "accepted_commit_now" status. Once the patch has been pushed, you need to change the status of the patch in Bugzilla to "committed" and close the bug if it is fully fixed.

To do this, git-bz has a wrapper around git push: git bz push origin master will work just like git push origin master, except it will let you make patch status changes and leave comments.

git push origin master will push the local changes from your master branch to the master branch in the main repository. Be sure that you want to push all your local commits before running it. Specifying the branch you want to push is particularly important if you have multiple branches set up with --track option. You can specify --dry-run option to the git push command you are intending to use if you want to see the effect it will have without actually pushing the changes.

If you work with multiple patches, it's recommend to set up your git-config so only the current branch is pushed:

  git config --global push.default upstream

Let other developers of the module you made a patch for know if you don't have Git commit access for GNOME and they will commit the patch for you.

How to rid your patch of trailing whitespaces

Trailing whitespaces cause warnings and we try to avoid them in our code.

Before submitting a patch, you can test if it has trailing whitespaces by using git format-patch, reverting, and re-applying it with git am which will show you the warnings if there are trailing whitespaces. You can then remove the trailing whitespaces by hand.

Setting Git to color-code patches will help you identify the trailing whitespaces by highlighting them in red when you use git diff and git show commands. For example, for identifying the trailing whitespaces in your last commit, you can run git show HEAD.

Another way to remove trailing whitespaces is to run:

  emacs <filename> -f delete-trailing-whitespace -f save-buffer -f kill-emacs

Though the occasional problem with it is that if there were already trailing whitespaces in the file not introduced by your patch, it will remove them too. However, we don't like patches that mix in random fixes, so you would have to undo those.