Skip to main content
Signal is an open-source project and welcomes contributions from the community. Reading this page before you start will save you time and help your work land successfully.

​
Development ideology

The Signal team holds six principles that shape every design decision in the app. Understanding them will help you write code that fits the project.
If you feel compelled to add a preference that is exposed to the user, it is very possible you have made a wrong turn somewhere. Simplicity is a feature.
Minimize the points at which a user is exposed to cryptographic terminology as much as possible. Abstractions must be invisible.
The idea that some users “understand” concepts better than others has proven to be, for the most part, false. If anything, so-called power users are more dangerous than the rest — avoid exposing dangerous functionality to them.
PGP is the guide for what not to do. Complexity, key management ceremony, and user-visible identifiers are all failure modes.
Be wary of anything that is anti-asynchronous: ACKs, protocol confirmations, or any protocol-level advisory message.
Protocol ideas that require synchronized clocks are doomed to failure.

​
Finding issues to work on

The GitHub issue tracker is used exclusively for bugs in the Android client — not feature requests or general discussion.

Bug tracker

Search open and closed issues before filing a new one. Every open issue is tracked and read by the team.

Community forum

Feature requests, larger change proposals, and general discussion belong on the community forum.
As a first-time contributor, pick a small and simple bug to fix. Most of the work goes into discovering which three lines need to change, not writing the code.
When searching for something to work on:
  • Look for issues labelled as good first candidates in the open issues list.
  • Propose larger features on the community forum before writing any code — large changes require coordination across Android, iOS, and Desktop.
  • Check closed issues to understand what has already been tried.

​
Signing the CLA

You must sign the Contributor License Agreement before your pull request can be merged.
Pull requests from contributors who have not signed the CLA cannot be merged, regardless of code quality.
Sign the CLA at signal.org/cla/. This is a one-time requirement per contributor.

​
Pull request guidelines

​
Smaller is better

Large pull requests are significantly less likely to be accepted. Big features often require protocol modifications and a staged rollout coordinated across millions of users on multiple platforms.
The Signal team is small. A focused PR with a clear scope is much easier to review and ship than a sprawling change.

​
Submit finished, well-tested PRs

  • Do not submit pull requests that are still a work in progress.
  • Test your changes thoroughly before opening a PR.
  • Follow the code style guidelines — run ./gradlew format before pushing.
  • One concern per pull request. Do not bundle unrelated fixes.

​
Be patient

If your pull request follows all the guidelines above but has not been merged, the team likely has not had time to review it yet. Merging can sometimes take a while.

​
Ways to contribute beyond code

Contributing to Signal does not require writing Kotlin or Java. There are several other valuable ways to get involved:

Translations

Help translate Signal into your language on the community forum’s translation section.

Bug reports

Write useful, reproducible bug reports. Search existing issues first to avoid duplicates.

Documentation

Improve the wiki, fix inaccuracies, or add missing information.

Donations

Signal is a non-profit. Donations help fund ongoing development and infrastructure.
You can also help by:
  • Redirecting support questions to support@signal.org and the Signal Support Center.
  • Redirecting non-bug discussions to the community forum.
  • Finding and marking duplicate issues.
  • Reproducing reported issues and adding troubleshooting details.
  • Testing other contributors’ pull requests.
  • Sharing Signal with friends and family.