This site has been archived. To learn more about our current products Ibexa Content, Ibexa Experience, Ibexa Commerce head over to the Ibexa Developer Portal

eZ Community » Learn » eZ Publish » How to contribute to eZ Publish using...

How to contribute to eZ Publish using Git

Tuesday 01 March 2011 10:07:20 pm

  • Currently 5 out of 5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

The different ways of contributing

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 !

 

1. How to Report

This section will be expanded in the future with more details but for reporting issues the most important things that should be mentioned are:

  • Title: A good title which shortly describes the issue, preferably so technical persons can understand the issue only by glancing at this
  • Description: A good description which expands on what is current behavior and what you would expect to be the correct behavior (and why especially in case of bug; api doc, online doc or assumption)
  • Affected Version: Signaling which version(s) are affected (in case of new feature you can skip this)
  • Environment: In case of bug mention your environment or several environments where issue has been reproduced (OS, filesystem, Database, PHP version & if specific to OS/FileSystem/Database version also mention that)

2. How to Test

To help out on confirming an issue, some options arises. First is to try to reproduce in as recent version as possible to rule out if issue is already solved, secondly if possible is to provide a test case which points out where the issue is. This can be archived on several levels;

  • Plain test case description, here as BDD as that is what we will standardize on in the near future, example:
    • Scenario: Editing a Folder and changing it's title should give Folder new url
      Given I am logged in as editor to admin interface
         And I go to folderX
      When I click edit
        And I set title to "new title"
        And I click publish
      Then I go to folderX
        And I am on "/new-title" page
    •  Description: Fails on last step, url still same as before editing
  • Automated testing, this speeds up identification of issue a lot and should therefor be consider as a way to report the issue, options from high level to low level (the lower level, the better precision):
    • Functional test: When user interface is expected to behave differently
    • Integration test: When API should produce a different outcome
    • Unit test: When a unit of code should behave in a different way

Note: Functional & integration tests are only available on "new stack" (aka "Symfony stack" or more precisely "6.x stack"), integration tests are for Public API and can be found here, functional tests will be available pr bundle.

3. 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 to issue

 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:

 1. Fork > 2. Create topic branch > 3. Do changes + Commit > 4. Push >  5. Create Pull request

 

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 reported issue 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 issue

 Make changes, commit, and repeat if you want to do several independent changes. Example, one for unit test and one for the fix:

  • Test EZP-19999: Add unit test for failing url handling
  • Fix EZP-19999: <issue title> 
 4. Push  At least once per issue  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. Create a pull request  Once per issue

 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. Example (Title + description):

 Fix EZP-19999: <issue title>

 Issue: <link>
 Issue was that method x does not check return value of y to be empty or not.
 

Locally you can iterate #3 several times before you push, keeping in-dependant changes separate from each other. After you have pushed and created pull requests you can ask people in the community 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 signal that the pull request is ready for merge.

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.

 
36 542 Users on board!

Tutorial menu

Printable

Printer Friendly version of the full article on one page with plain styles

Author(s)

Proudly Developed with from