How to contribute to eZ Publish using Git
Tuesday 01 March 2011 1:07:20 pm
The different ways of contributing
While waiting for the upcoming changes to how development is done (soon decided upon by the Community Project Governance ), here are your current options when it comes to contributing to eZ Publish Community Project :
- Reporter - Issue reporter, creates issues in issue tracker (http://issues.ez.no/ezpublish)
- Tester - Provide reduction test cases, reproduce and confirm issues
- Collaborator - Contribute code with unit tests and api doc on issues created by yourself or others. A patch could also just fix api doc, improve unit tests or other non functional stuff, in that case there doesn’t need to be an issue for it.
As you can see, you don’t necessarily need to be a developer to contribute to an open source project, and same goes for eZ Publish Community Project. The whole “Reporting issues > Reproduce and confirm issue > Adding some more info on steps to reproduce > Finding some more information on what triggers the issue“ process, is of tremendous help and makes sure that issues are looked at more quickly. But if you are a developer, it will be looked at even more quickly if there is already a fix for it...read on !
How to collaborate
From a bird-eye view, there are two workflows for contributing code. The first one is similar to how it is done with SVN:
1. Do changes > 2. Create patch > 3. Reset your checkout > 4. Upload somewhere
And then iterate the whole process starting by applying the latest patch if there are more changes to be made.
But that is not really taking advantage of Git and Github, so to do that we’ll promote the Github workflow in this article:
0. Fork > 1. Create topic branch > 2. Do changes + Commit > 3. Push
| Step | How many times do I do this ? | What is it exactly ? |
|---|---|---|
| 1. Fork | Once | Creating a copy of the main eZ Publish repository, logically linked with the original one. The Git way. All it takes is one click. |
| 2. Create topic branch | For every topic you address (bug-fix, feature) | Keeping your development efforts in a clean space in your Git version of eZ Publish. Lets you work on other parts of eZ Publish if you want to, with no conflict. Branching is seamless with Git. |
| 3. Do changes + Commit | At least once per topic | Make changes, commit, and repeat if you want to do several independent changes. |
| 4. Push | At least once per topic | Synchronizing your local Git clone with your account on github. After you have pushed you can ask people for feedback on your commits and then re-iterate 2 and 3 until you are happy with the state of your branch, at that point you can create a “Pull Request” (see further below). |
| 5. Emit a pull request | At least once per topic | Once satisfied with your bug-fixing or feature development job, sending your changes back to the main eZ Publish Gitrepository, so that others can see them or elaborate on them. This happens on Github, and is equivalent to asking the ‘ezsystems’ user to merge in your changes. |
Locally you can iterate #3 several times before you push, keeping in-dependant changes separate from each other. After you have pushed you can ask people for feedback on your commits and then re iterate 2 and 3 until you are happy about the state of your branch, at that point you can create a “Pull Request” on Github asking the ‘ezsystems’ user to merge in your changes.
As you could notice we start using the Git/Github jargon here. If you are not super acquainted with it, we recommend to read the appendix section.