Contributing to Apache log4php

Thank you for considering contributing to Apache log4php. This document describes the contributor workflow.

Clone the repository

The first step is to clone the source repository and check out the develop branch, from which all work should start.

$ git clone https://git-wip-us.apache.org/repos/asf/logging-log4php.git log4php
$ cd log4php
$ git checkout -b develop origin/develop

Make sure you have user.name and user.email git options populated with your name and email address.

You can set these values locally for the current project:

$ git config user.name "Ivan Habunek"
$ git config user.email ihabunek@apache.org

Or globally, in which case they will be applied to all projects:

$ git config --global user.name "Ivan Habunek"
$ git config --global user.email ihabunek@apache.org

To check if your setting are set, run:

$ git config --list | grep ^user
user.name=Ivan Habunek
user.email=ihabunek@apache.org

Git workflow

Let's say that you have decided to work on the LOG4PHP-203 JIRA issue.

Create a topic branch

It is a good idea to do all work in separate "topic" branches. This way you can update the master and develop branch without worrying about conflicts.

Topic branches should be based on develop branch. In this example, we will name it "issue-203" to reflect the work.

To create one:

$ git checkout develop
$ git checkout -b issue-203
$ git branch
  develop
* issue-203
  master

Make and commit changes

At this point you can work on the code to fix the issue. For example, you have worked on src/main/php/appenders/LoggerAppenderMongoDB.php.

$ git status
# On branch issue-203
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   src/main/php/appenders/LoggerAppenderMongoDB.php
#
no changes added to commit (use "git add" and/or "git commit -a")

Add and commit the files you worked on.

Commit messages should be signed off. This means adding Signed-off-by: Name <email> to the commit message. Git will do this automatically if the --signoff option is used.

$ git add src/main/php/appenders/LoggerAppenderMongoDB.php
$ git commit --signoff

Please write good commit messages, as this helps the project memebers to understand the changes contained in a commit. A good commit message looks like this:

Header line: issue id, short description in one line

Body of the commit message can contain multiple lines of text which 
explain the commit in more detail. It is separated by the header line
by an empty line.

Feel free to include multiple paragraphs, as much as is needed to
describe the changes well. Please wrap the commit mesasges to 74
characters. That way 'git log' will display the messages nicely, even
if indented.

Signed-off-by: Your Name <your@email.com>

The header really should only be one line, it should shortly state what is changed. If it fixes an issue, it should start with the issue ID (e.g. "LOG4PHP-203").

Try to keep you commits small so it's easier to track what is being done. It's ok to have multiple commits within a single contribution.

Create a patch

Once you have done all the work needed, you should format a patch which includes your commits since branching from develop:

$ git format-patch develop

This will create a patch per commit. Alernatively, create a single patch:

$ git format-patch develop --stdout > issue-203.patch

Now you can either attach the patch to the JIRA issue, or send it to the the dev mailing list (log4php-dev@logging.apache.org). The developers will review your patch, and if everything is ok it will be applied on the develop branch.

Once your patch is applied, ckeck it out:

$ git checkout develop
$ git pull origin develop
$ git log

You can now delete your topic branch:

$ git branch -d issue-203

And move on to the next issue.

Contributing (last edited 2013-01-05 09:34:33 by IvanHabunek)