How to contribute to eZ Publish using Git

Working with topic branches

A topic branch is a branch specifically created for an issue or a collection of related issues, or even a new feature. From a SVN background this might sound crazy. But with Git branching is cheap and makes the whole process simpler, retains history and allows online reviews on github. Here is how to create the topic-branch:

Checkout

1. If you haven't created topic branch yet:

   $ git checkout -b <topic-branch> upstream/master

2. If you already have the branch, but only remotely in your fork:

   $ git checkout -b <topic-branch> origin/<topic-branch>

   And specify that it should track upstream/master:

   $ git config branch.<topic-branch>.remote upstream/master

3. If you have the branch locally already (check with “$ git branch”):

   $ git checkout <topic-branch>

Topic branch name should be something that identifies issue, so one or two keywords and issue number separated by hyphen, eg: rss-nbsp-016953 for “#016953: breaks RSS/ATOM feeds” issue, or if your going to address a collection of related issues something like eg: rss-improvments. If you are starting a feature, be explanatory in the name too, yet don’t write your life in it.

Make changes

 Make all independent changes one at a time, code should be workable, clean and testable before you go ahead and push. Meaning no debug code or var_dump calls.
Bug fixing example, full work-flow :

1. Pull in changes using “$ git pull”
2. First add a unit test that triggers the issue and fails, then commit (see below)
3.  Fix the issue commit (see below), then commit
4. Switch from doxygen to phpdoc on the php functions you touch, then commit (see below)
5.  Push (see below)

Commit

If you have added new files, use “$ git add <file>” to stage them for commit.
Then the most common ways to do commits (#B is preferred):

A. Only summary

$ git commit -am "Fixed #<issue_id>: <issue_title>"

B. With a message

Useful when you do several commits to same issue / topic and want to add a note on the changes you do in-between. Also, and most importantly, write why you do the change, especially if there is no issue that explains the why! Start with the summary as above and add an empty line before the body of the commit message.

Remember that lines starting with # are treated as comments and will not be part of the commit message, and please always use utf-8. For more info, see the git user guide. For reviewer / issue-creator / patch-provider credit and attribution follow the svn convention

$ git commit -a

Git will open your default editor to edit commit message, change it to something like this and save + close (example text):

Fixed #<issue_id>: <issue_title>

Extended signature of function X to allow caller to specify the user instance instead of only using current logged in user.

Review by: Eagle Eyes
          ar
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
(...)

Note: “Fixed” is used if issue is a bug, if it is an enhancement, use “Implemented”!

If you are not confident in your fix then it is better to create a patch and upload it to the issue tracker under the related issue (cf “Working with Git patches” a bit below). When uploading your patch, feel free to engage a conversation around it (adding a comment to your patch upload, simply), explaining why you are not sure about it, what you would like to clarify, etc.

Push

When you feel confident that you want to share your work with the world, you’ll want to push. But since our topic branch tracks another branch (probably upstream/master) we should always specify target using:

$ git push origin <topic-branch>

When this is done, git will respond with something like “Your branch is ahead of 'upstream/master' by 1 commit.” basically giving you an idea on how many differences there are between your topic branch and the branch you track (master). This is also shown when you use “$ git status”. You may also see statuses like “Your branch .. is ahead .. with 1 commits and behind by 50 commits” meaning you have 1 commit in your topic branch and 50 new commits in master since you last pulled in changes.

Add comment on issue

 Now to make anyone following the issue aware of the fix, add a comment like this on issue in issue tracker with correct link to the commit :

Fixed in <user> fork:
master(4.5.0alpha3) http://github.com/<user>/ezpublish/commit/<commit_sha>

Pull Request

 When you are confident that your contribution is ready for inclusion in eZ Publish, then all you need to do is click on “Pull request” in the Github GUI on the specific topic branch as selected using the “Switch Branches” drop-down.

Tagging a “finished” branch (optional)

When work on a branch has concluded, it is a good idea to convert it into a tag, to avoid cluttering up your branch list with inactive branches, but to still keep track of the changes and commits inside that branch. This can be done by the following command, when being inside the working directory of your checked out branch:

$ git tag -am “Message describing the tag” <tagname>

Leaving out the last parameter will tell git to point the tag to the latest commit on that branch, which is what you want in this case. Converting branches to tags, is particularly useful when you are dealing with a form of old, inactive release branches, where you do want to keep it, but are no longer working actively on it.

If a branch has been merged back to its upstream source, been tagged or both it can be deleted. You accomplish this by:

$ git -d <branch name>

Note the lower case ‘d’, this is a safety precaution, git will warn you and stop, if it detects that you are trying to delete a branch which has not yet been merged, or has another ref tracking it (such as a tag). This is for your benefit, and to make sure that you don’t lose any data.

Following these suggestions you should be able to keep mind and repository clean, but yet keep all history of your work as you please.