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 firstname.lastname@example.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 email@example.com
To check if your setting are set, run:
$ git config --list | grep ^user user.name=Ivan Habunek firstname.lastname@example.org
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 <email@example.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 (firstname.lastname@example.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.