Contributing via Git & Github (WIP)

Git Repositories

The project maintains several repositories:

Setting up your own Git Clone

Forking the OFBiz repositories

Forking the OFBiz repository in Github is - in essence - having your clone of the OFBiz repository in the Github environment, thereby being publicly available to the community and others.

This is done by clicking on the 'Fork' button on the repository's page in Github (see public locations above).

From here you can clone or download it to your local development environment (and use it within your preferred IDE). You can do this via the green 'Clone or Download' button on your repository page, or directly in your preferred location (folder) on your local environment, with a command as decribed in the 'Cloning your Github fork' section.

Cloning your Github fork

A Git clone is your remote git clone existing in your local environment.

Cloning is done through following commands in your cli:

git clone https://github.com/<your_github_id>/ofbiz-framework

git clone https://github.com/<your_github_id>/ofbiz-plugins

git clone https://github.com/<your_github_id>/ofbiz-site

git clone https://github.com/<your_github_id>/ofbiz-tools

Invoking the git clone command as outlined above will ensure that your local clone has link to your Github repository. By invoking the git remote -v command you get an overview of all associated remote repositories.

Keeping your local clone in sync with changes in the official repositories

Accepted commits will be merged regularly in one of the branches in the repository by one of the committers. In order to ensure that you're working with the latest from the official repository (to avoid merge conflicts), it is of the utmost importance that you regularly bring the changes from the OFBiz repository to your local clone. 

In order to do this you need to set up a connection to the official repository. This is done by executing one of following git commands in your environment (in the folder of your local clone):

1. for ofbiz-framework: git remote add OFBiz https://github.com/apache/ofbiz-framework.git

2. for ofbiz-plugins: git remote add OFBiz https://github.com/apache/ofbiz-plugins.git
3. for ofbiz-site: git remote add OFBiz https://github.com/apache/ofbiz-site.git
4. for ofbiz-tools: git remote add OFBiz https://github.com/apache/ofbiz-tools.git

and update your local clone via git fetch, followed by git rebase.

Working on your enhancements for the project

Enhancements to the codebases of our project always start from somewhere. For our project this driven by one or more open issues (tickets) existing in our JIRA (https://issues.apache.org/jira/projects/OFBIZ), see also the section 'Reporting Code Issues' below.

New development branches

When you are about to start working on a ticket, it is advised to create a new development branch based on one of the official branches. 

This is done via the git branch command from the checkout out branch. It is advised to name the branch in reference to the ticket, eg. the ticket id. As an example:

git branch OFBIZ-12345

The invoked git branch command will switch you automatically to the newly created branch to ensure your changes go into the correct one.

From Work-In-Progress to commit

Each time you save a code artefact in your development environment it isn't submitted as a commit to the branch. Instead it is - until a commit action - a work in progress, and pushes to remote repositories (e.g your repository on Github) will not contain your saved changes.

In order to get your saved changes committed to the branch you have to invoke the git commit command. On committing your changes you are advised to set a commit message in accordance with the commit protocol as explained in OFBiz commit message template.

Squashing  your commits

When working on a ticket in your local development branch it may be so that you have multiple commits before it is ready to be contributed to the project. In such a case and as a last step you should squash  all your commits.

Remark: When collaborating with fellow community members, you should NEVER squash the commits of those authors as it will rewrite history and the attribution is lost.

Getting your contributions accepted

In order to get your contributions (commits) accepted by the project's committers, ensure that:

1. your code changes are in accordance to the project's coding guidelines, see Coding Conventions;
2. you have tested your changes;
3. your commit message is in accordance with the project's commit-message, template, see OFBiz commit message template.

Making your commits available to community members (pushing to Github)

After having committed your changes to your local branch you may want to make those publicly available - in your public repository on Github - to your fellow community members for evaluation. This is done via the git push command, e.g

git push origin OFBIZ-12345

The example above sends your committed changes to your public repository on Github, as your local clone was established from there (see the 'Cloning your Github fork' section above).

Pull Requests

Pull requests are the means to inform fellow community members that your changes are available for review. 

Pull requests (e.g. from Github) can be handled in the same way as patch files in a JIRA ticket. In general, patch files are downloaded from the ticket and then applied to a branch in the development environment (e.g. your IDE) for evaluation and testing purposes.

Creating a Pull Request

After having you pushed your development branch to your public repository on Github, you are ready to submit a Pull Request. The best approach is to go into the branches section, where your development branches will be visible.

There you select the development you want to generate the Pull Request from, by clicking the 'New Pull Request' button.

Handling a Pull Request (for committers)

@todo

Collaborating with community members

@todo

Git GUI Clients

Instead of working via the cli (terminal) that comes with your OS, you can also use dedicated Git GUI clients (software packages) to execute git commands.

An overview of clients available (for your os platform) can be found here: https://git-scm.com/downloads/guis

Of course, you can also use the git functionalities available in your IDE of choice (Apache Netbeans, Eclipse, IntelliJ, etc.)

Reporting Code Issues

The project's tool to report and track progress on issues with code in the various repositories is JIRA (https://issues.apache.org/jira/projects/OFBIZ). 

While Github also offers functionality to report issues, there is no bidirectional way to sync these with JIRA. Therefore, it is advised to register issues in JIRA as tickets there appear in the project's mailing lists to reach its community members in a better way.