Skip to content

Latest commit

 

History

History
72 lines (43 loc) · 6.02 KB

CONTRIBUTING.md

File metadata and controls

72 lines (43 loc) · 6.02 KB
Raw

Contributing code to ODK Aggregate

This is a living document. If you see something that could be improved, edit this document and submit a pull request following the instructions below!

Submitting a pull request

To contribute code to ODK Aggregate, you will need to open a pull request which will be reviewed by the community and then merged into the core project.

  1. Set up your development environment.

  2. To make sure you have the latest version of the code, set up this repository as a remote for your fork and then sync your fork.

  3. Create a branch for the code you will be writing:

     git checkout -b NAME_OF_YOUR_BRANCH

  4. If there is an issue corresponding to what you will work on, put @opendatakit-bot claim as a comment on issue to say you are claiming it. If there is no issue yet, create one to provide background on the problem you are solving.

  5. Once you've made incremental progress towards you goal, commit your changes with a meaningful commit message. Use keywords for closing issues to refer to issues and have them automatically close when your changes are merged.

     git commit -m "Do a thing. Fix #1."

  6. Push changes to your fork at any time to make them publicly available:

     git push

  7. Once you have completed your code changes, verify that you have followed the style guidelines.

  8. When your changes are ready to be added to the core ODK Aggregate project, open a pull request. Make sure to set the base fork to opendatakit/aggregate. Describe your changes in the comment, refer to any relevant issues using keywords for closing issues and tag any person you think might need to know about the changes.

  9. Pull requests will be reviewed when committers have time. If you haven't received a review in 10 days, you may notify committers by putting @opendatakit/aggregate in a comment.

Making sure your pull request is accepted

  1. Confirm that your code compiles.

  2. Verify the functionality. Ideally, include automated tests with each pull request. If that's not possible, describe in the pull request comment which cases you tried manually to confirm that your code works as expected. Attach a test form when appropriate. This form should only include questions which are useful for verifying your change.

  3. Make sure that there is an issue that corresponds to the pull request and that it has been discussed by the community as necessary.

  4. Keep your pull request focused on one narrow goal. This could mean addressing an issue with multiple, smaller pull requests. Small pull requests are easier to review and less likely to introduce bugs. If you would like to make stylistic changes to the code, create a separate pull request.

  5. Write clear code. Use descriptive names and create meaningful abstractions (methods, classes).

  6. Document your reasoning. Your commit messages should make it clear why each change has been made.

  7. If your pull request makes user-facing changes, we likely need to update documentation. File an issue on the docs repo describing the changes.

  8. Follow the guidelines below.

The review process

Bug fixes, pull requests corresponding to issues with a clearly stated goal and pull requests with clear tests and/or process for manual verification are given priority. Pull requests that are unclear or controversial may be tagged as needs discussion and/or may take longer to review.

We try to have at least two people review every pull request and we encourage everyone to participate in the review process to get familiar with the code base and help ensure higher quality. Reviewers should ask themselves some or all of the following questions:

  • Was this change adequately discussed prior to implementation?
  • Is the intended behavior clear under all conditions?
  • What interesting cases should be verified?
  • Is the behavior as intended in all cases?
  • What other functionality could this PR affect? Does that functionality still work as intended?
  • Was the change verified with several different devices and Android versions?
  • Is the code easy to understand and to maintain?
  • Is there sufficient detail to inform any changes to documentation?

Pull requests that need more black-box testing are tagged with needs testing. Pull requests that need more complete reviews including black-box testing but also review of approach and/or appropriateness are tagged with reviews wanted. Any contributor is encouraged to participate in both kinds of reviews!

Small fixes that target very particular bugs may occasionally be merged without a second review.

Style guidelines

Follow the Google Java style guide.

Code from external sources

ODK Aggregate is released under the Apache 2.0 license. Please make sure that any code you include is an OSI-approved permissive license. Please note that if no license is specified for a piece of code or if it has an incompatible license such as GPL, using it puts the project at legal risk.

Sites with compatible licenses (including StackOverflow) will sometimes provide exactly the code snippet needed to solve a problem. You are encouraged to use such snippets in ODK Aggregate as long as you attribute them by including a direct link to the source. In addition to complying with the content license, this provides useful context for anyone reading the code.