How to Contribute to Sentry
This page describes the mechanics of how to contribute new software to Sentry.
Getting the source code
Sentry uses git for version control.
Get the source code on your machine using Git. All development is done on branch "master".
Modify the source code in your favorite editor to add the new feature, enhancement or bug fix.
But take care about the following points
- All public classes and methods should have informative Javadoc comments.
- Do not use @author tags.
- Contributions should pass existing unit tests.
- New unit tests should be provided to demonstrate bugs and fixes. JUnit is our test framework:
Generating a patch
Please make sure that all unit tests pass before posting your patch and that no new javac compiler warnings are introduced by your patch.
After a while, if you see
all is ok, but if you see
then please examine error messages and fix things before proceeding.
Creating a patch
Check to see what files have been modified,
Add the files to the list of changes to be committed with:
Commit the changes locally with:
In order to create a patch, type:
Read the patch file. Make sure it includes ONLY the modifications required to fix a single issue.
Please do not:
- reformat code unrelated to the bug being fixed: formatting changes should be separate patches/commits.
- comment out code that is now obsolete: just remove it.
- make things public which are not required by end users.
- comment code whose function or rationale is not obvious;
- name the patch file after the JIRA – SENTRY-<JIRA#>.patch
Testing your patch
Before submitting your patch, you are encouraged to run the same tests a committer will run before committing your changes. This enables you to fix problems with your patch before you submit it. The
test maven target will run your patch through the entire test suite.
To use this target, run:
At the end, you should get a message on your console that indicates success.
Some things to note:
- you may need to explicitly set MAVEN_HOME.
- you may need to explicitly set JAVA_HOME.
Running RAT checks
Before submitting your patch, please run RAT check to make sure all the files have the necessary license headers.
To do so, run:
Applying a patch
To apply a patch either you generated or found from JIRA, you can issue
if you just want to check whether the patch applies you can run patch with --dry-run option
Contributing your work
Finally, patches should be attached to an issue report in Jira via the Attach File link on the issue's Jira. Please add a comment that asks for a code review. Please note that the attachment should be granted license to ASF for inclusion in ASF works (as per the Apache License §5).
When you believe that your patch is ready to be committed, select the Submit Patch link on the issue's Jira.
If your patch implements a major feature or improvement, then you must fill in the Release Note field on the issue's Jira with an explanation of the feature that will be comprehensible by the end user.
Please be patient. Committers are busy people too. If no one responds to your patch after a few days, please make friendly reminders. Please incorporate other's suggestions into your patch if you think they're reasonable. Finally, remember that even a patch that is not committed is useful to the community.
In some cases a patch may need to be updated based on review comments. In this case the updated patch should be re-attached to the Jira with the same name. Jira will archive the older version of the patch and make the new patch the active patch. This will enable a history of patches on the Jira. As stated above patch naming is generally SENTRY-#.patch where SENTRY-# is the id of the Jira.
Please comment on issues in Jira, making their concerns known. Please also vote for issues that are a high priority for you.
Contributors should join the Sentry mailing lists. In particular, the email@example.com list (to see changes as they are made), the firstname.lastname@example.org list (to join discussions of changes).
Apache Sentry is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the name of Apache TLP sponsor. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.