Contributing code to Mozilla's Android projects
Thank you for taking the time to contribute to one of Mozilla's Android
Before contributing, please review our Community Participation Guidelines.
If you run into trouble at any point, ask for help! Check out our preferred communication channels.
Unfamiliar with the technology we use? No problem! We were once new to this too! Here are few guides we've compiled to help you get started:
If these are confusing or if you have questions, please let us know!
Finding issues to work on
New to Mozilla's mobile projects? See issues labeled
good first issue in your project's
issues tracker (example: focus-android). These are designed to be
easier to implement so you can focus on learning our pull request workflow. Please only
fix one of these.
Looking for more challenging issues? See issues labeled
help wanted (example:
focus-android). These are issues that are ready to be implemented without
additional product or UX discussion.
When you find an issue you'd like to work on, comment on the issue saying that you'd like to work on it. This ensures it is still available for you to work on.
If you want to work on a new feature, always file an issue first and wait for our team to discuss it. We want to ensure all teams (product, ux, engineering) have an opportunity to provide feedback. Pull requests for unsolicited features are unlikely to get merged.
Creating a Pull Request
An example commit message summary looks like,
Closes #5: Upgrade gradle to v1.3.0.
Please follow these guidelines for your pull requests:
- All Pull Requests should address an issue. If your pull request doesn't have an
issue, file it!
- GitHub search defaults to issues, not PRs, so ensuring there is an issue for your PR means it'll be easier to find
- The commit message summary should briefly describe what code changed in the commit, not
the issue you're fixing.
- We encourage you to use the commit message body to elaborate what changed and why
- Include the issue number in your commit messages. This links your PR to the issue it's
intended to fix.
- If your PR closes an issue, include
Closes #...in one of your commit messages. This will automatically close the linked issue (more info).
- If your PR closes an issue, include
- Prefer "micro commits".
- A micro commit is a small commit that generally changes one thing. A single Pull Request may comprise of multiple incremental micro commits.
- A series of micro commits should tell a story. For example, if your goal is to add a new icon to the toolbar, you can make a commit to add the icon asset and then make a commit to use the icon in the code.
- Commits should generally not undo the work of previous commits in the same PR.
- If you're not comfortable making micro commits, it's okay to begin contributing without them.
- Add a reviewer to ensure someone sees, and reviews, your pull request so it can be merged
- If the tests fail, please try to fix them! Keeping the tests passing ensures our code isn't broken and the code is unlikely to get merged without passing tests. If you run into trouble, ask for help!
- If there are UI changes, include a screenshot so UX can also do a visual review
- When in doubt, look at the closed PRs in the repository to follow as an example or ask us online!
If your code is not approved, address the suggested comments, push your changes, and re-request review from your reviewer again.
After your code has been approved and the tests pass, your code will be merged into master by the core team. When merging, we use GitHub's "Rebase and merge":
- We keep a linear git history for readability
- We prefer incremental commits to remain in the history
- It's easier to read, helps with bisection, and matches repo state during review.
To learn more about how our tests are structured, see testing.md.