You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

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".

git remote add apache-sentry https://git-wip-us.apache.org/repos/asf/incubator-sentry.git
git fetch apache-sentry
git checkout -b local-master apache-sentry/master

Making Changes

Before you start making changes, send an email to the dev list, or file a new issue using JIRA. Describe what your trying to do and how it will benefit the project.

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

Unit Tests

Please make sure that all unit tests pass before posting your patch and that no new javac compiler warnings are introduced by your patch.

mvn clean test -Pdownload-hadoop

After a while, if you see

BUILD SUCCESSFUL

all is ok, but if you see

BUILD FAILED

then please examine error messages and fix things before proceeding.

Creating a patch

Check to see what files have been modified,

git status

Add the files to the list of changes to be committed with:

git add  <filename>
git add  <filename>

Commit the changes locally with:

git commit -m "JIRA-#: JIRA title"

In order to create a patch, type:

git diff --no-prefix HEAD^ > SENTRY-{JIRA#}.patch

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.

Please do:

  • 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:

mvn test -Pdownload-hadoop

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.

Applying a patch

To apply a patch either you generated or found from JIRA, you can issue 

patch -p0 < SENTRY-<JIRA#>.patch

if you just want to check whether the patch applies you can run patch with --dry-run option

patch -p0 --dry-run < SENTRY-<JIRA#>.patch

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.

Jira Guidelines

Please comment on issues in Jira, making their concerns known. Please also vote for issues that are a high priority for you.

Stay involved

Contributors should join the Sentry mailing lists. In particular, the commits@sentry.incubator.apache.org commits list (to see changes as they are made), the dev@sentry.incubator.apache.org dev list (to join discussions of changes).

See Also

  • No labels