Contributing to Apache Phoenix
General process
The general process for contributing code to Phoenix works as follows:
- Discuss your changes on the dev mailing list
- Create a JIRA issue unless there already is one
- Setup your development environment
- Prepare a patch containing your changes
- Submit the patch
These steps are explained in greater detail below.
Note that the instructions below are for the main Phoenix project. Use the corresponding repository for the other subprojects. Tephra and Omid also have their own JIRA project
Discuss on the mailing list
It’s often best to discuss a change on the public mailing lists before creating and submitting a patch.
If you’re unsure whether certain behavior in Phoenix is a bug, please send a mail to the user mailing list to check.
If you’re considering adding major new functionality to Phoenix, it’s a good idea to first discuss the idea on the developer mailing list to make sure that your plans are in line with others in the Phoenix community.
Log a JIRA ticket
The first step is to create a ticket on the Phoenix JIRA.
Setup development environment
To setup your development, see these directions.
Generate a patch
There are two general approaches that can be used for creating and submitting a patch: GitHub pull requests, or manually creating a patch with Git. Both of these are explained below. Please make sure that the patch applies cleanly on all the active branches including master and the unified 4.x branch.
Regardless of which approach is taken, please make sure to follow the Phoenix code conventions (more information below). Whenever possible, unit tests or integration tests should be included with patches.
Please make sure that the patch contains only one commit and click on the ‘Submit patch’ button to automatically trigger the tests on the patch.
The commit message should reference the jira ticket issue (which has the format PHOENIX-{NUMBER}:{JIRA-TITLE}).
To effectively get the patch reviewed, please raise the pull request against an appropriate branch.
Naming convention for the patch
When you generate the patch, make sure the name of the patch has following format: PHOENIX-{NUMBER}.{BRANCH-NAME}.{VERSION}.patch
Ex. PHOENIX-4872.master.v1.patch, PHOENIX-4872.master.v2.patch, PHOENIX-4872.4.x-HBase-1.3.v1.patch etc
GitHub workflow
- Create a pull request in GitHub for the mirror of the Phoenix Git repository.
- Generate a patch and attach it to the jira, so that Hadoop QA runs automated tests.
- If you update the PR, generate a new patch with different name from the previous, so that change in the patch is detected and tests are run on the new patch.
Local Git workflow
- Create a local branch git checkout -b <branch name>
- Make and commit changes
-
Generate a patch based on the name of the JIRA issue, as follows:
git format-patch --stdout HEAD^ > PHOENIX-{NUMBER}.patch
-
Attach the created patch file to the jira ticket
Code conventions
The Phoenix code conventions are similar to the Sun/Oracle Java Code Convention. We use 4 spaces (no tabs) for indentation, and limit lines to 100 characters.
Eclipse code formatting settings and import order settings (which can also be imported into Intellij IDEA) are available in the dev directory of the Phoenix codebase.
All new source files should include the Apache license header.
Committer workflow
In general, the “rebase” workflow should be used with the Phoenix codebase (see this blog post for more information on the difference between the “merge” and “rebase” workflows in Git).
A patch file can be downloaded from a GitHub pull request by adding “.patch” to the end of the pull request url, e.g. https://github.com/apache/phoenix/pull/35.patch
When applying a patch contributed from a user, please use the “git am” command if a fully-formatted patch file is available, as this preserves the contributor’s contact information. Otherwise, the contributor’s name should be added to the commit message.
If a single ticket consists of a patch with multiple commits, the commits can be squashed into a single commit using git rebase.