Welcome contributors! We strive to include everyone's contributions. This page provides necessary guidelines on how to contribute effectively towards furthering the development and evolution of Sentry. You should also read the guide on setting up Development environment where you will find details on how to checkout, build and test Sentry.
Note: This guide applies to general contributors. If you are a committer, please read the How to commit as well.
There are many ways you can contribute towards the project. A few of these are:
Jump in on discussions: It is possible that someone initiates a thread on the mailing list describing a problem that you have dealt with in the past. You can help the project by chiming in on that thread and guiding that user to overcome or workaround that problem or limitation.
File Bugs: If you notice a problem and are sure it is a bug, then go ahead and file a JIRA. If however, you are not very sure that it is a bug, you should first confirm it by discussing it on the Mailing Lists.
Review Code: If you see that a JIRA ticket has a "Patch Available" status, go ahead and review it. It cannot be stressed enough that you must be kind in your review and explain the rationale for your feedback and suggestions. Also note that not all review feedback is accepted - often times it is a compromise between the contributor and reviewer. If you are happy with the change and do not spot any major issues, then
+1 it. More information on this is available in the following sections.
Provide Patches: We encourage you to assign the relevant JIRA issue to yourself and supply a patch for it. The patch you provide can be code, documentation, build changes, or any combination of these. More information on this is available in the following sections.
Documentation: Contribute to the Sentry documentation by adding descriptions of new features, updating outdated documentation, and filling in documentation gaps.
In order to provide patches, follow these guidelines:
Make sure that all unit/integration tests are passing, and that the functionality you have worked on is tested through existing or new tests. JUnit is our test framework.
mvn clean install -DskipTests (compile) mvn test (run all tests)
After a while, if you see
all is ok, but if you see
then please examine error messages and fix things before proceeding.
-12345.patch, or SENTRY
12345is the JIRA number. You might want to name successive versions of the patch something like SENTRY
-12345.003.patch, etc. as you iterate on your changes based on review feedback and re-submit them.
The command to generate the patch is "git diff". Example:
$ git diff > /path/to/SENTRY-1234.001.patch for Branch $ git diff > /path/to/SENTRY-1234.001-branch1.patch
Read the patch file. Make sure it includes ONLY the modifications required to fix a single issue.
Please do not:
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:
mvn verify -DskipTests
You can apply someone else's patch with the GNU
patch tool. Example:
$ cd ~/workspace/sentry # or wherever you keep the root of your Sentry source tree $ patch -p1 < SENTRY-1234.001.patch
patchtool asking which file you want to patch, try variously the "-p1" or "-p0" flags to
patch. Without any additional arguments,
git diffgenerates patches that are applied using
patch -p1. If you use
git diff --no-prefixto generate your patch, you have to apply it using
patch -p0. The ReviewBoard tool understands both formats and is able to apply both types automatically.
Setup your ~/.reviewboardrc with the following content
REVIEWBOARD_URL = "https://reviews.apache.org/" REPOSITORY = 'Sentry' TARGET_GROUPS = 'sentry'
You can setup your username password like
rbt setup-repo --username=xx --password=xx
Post the review: Commit your changes to your local repo and do:
rbt post -g
Updating your review: append your changes the original commit and
rbt post -r=<review#>
Sentry uses the Apache Review Board for doing code reviews. In order for a change to be reviewed, it should be attached to the JIRA and posted on the review board. If the change is a minor change affecting only few lines and does not seem to impact main logic of the affected sources, it need not be posted on the review board. However, if the code change is large or otherwise impacting the core logic of the affected sources, it should be posted on the review board. Feel free to comment on the JIRA requesting the assignee to post the patch for review on review board.
Note: Not all patches attached to a JIRA are ready for review. Sometimes the patches are attached just to solicit early feedback regarding the implementation direction. Feel free to look it over and give your feedback in the JIRA as necessary. Patches are considered ready for review either when the patch has been posted on review board, or the JIRA status has been changed to 'Patch Available'. Find here a list of Sentry JIRAs marked Patch Available.
The net outcome from the review should be the same - which is to ensure the following:
Following are some guidelines on how to do a code review. You may use any other approach instead as long as the above stated goals are met. That said, here is an approach that works fine generally:
Once you have collected your comments/concerns/feedback you need to send it to back to the contributor. In doing so, please be as courteous as possible and ensure the following:
Once you have provided your feedback, wait for the developer to respond. It is possible that the developer may need further clarification on your feedback, in which case you should promptly provide it where necessary. In general, the dialog between the reviewer and developer should lead to finding a reasonable middle ground where key concerns are satisfied and the goals of the review have been met.
If a change has met all your criteria for review, please
+1 the change to indicate that you are happy with it.
Before you edit the Sentry documentation, create a JIRA with the Docs component to track documentation changes. Request access to this wiki from the Sentry PMC and make the required changes. There is no formal review process for the wiki, but it is always a good idea to have the documentation reviewed before closing the JIRA.
Contributors should join the Sentry mailing lists. In particular, the firstname.lastname@example.org list (to see changes as they are made), the email@example.com list (to join discussions of changes).