Code style

Signal Android enforces consistent code style through automated formatting and lint checks. Before submitting a pull request, make sure your changes pass both.

Running the formatter

The project uses ktlint version 1.5.0 for Kotlin formatting. A top-level Gradle task applies formatting across all modules — including the build-logic included build:

./gradlew format

This task runs ktlintFormat on every subproject and on the build logic plugins and tools. Run it before every commit.

./gradlew format modifies files in place. After running it, stage any changed files before committing.

Setting up lefthook

Lefthook enforces formatting automatically as a git pre-push hook. The project ships a lefthook.yml configuration at the repository root:

pre-push:
  commands:
    format:
      run: ./gradlew format --quiet && test -z "$(git status --porcelain)"
      fail_text: "Formatting changes detected. Please commit them and push again."

When you push, lefthook runs ./gradlew format and then checks whether any files were modified. If formatting changes are detected, the push is blocked and you must commit the changes before pushing again.

Installing lefthook

Install lefthook

Follow the installation instructions for your operating system. On macOS with Homebrew:

brew install lefthook

Enable the hooks

From the repository root, run:

lefthook install

This installs the git hook defined in lefthook.yml into .git/hooks/.

Override locally if needed

Create a lefthook-local.yml file (it is gitignored) to override settings for your local environment. See the lefthook documentation for details.

Kotlin conventions

New code should be written in Kotlin. Follow standard Kotlin idioms and the official Kotlin coding conventions, with the following project-specific notes:

Null safety: prefer non-null types. Use ?. and ?: rather than manual null checks where possible.
object for singletons: application-scoped singletons use Kotlin object declarations (see AppDependencies).
Lazy initialization: use by lazy { ... } for singletons that should be initialized on first access.
Extension functions: use them to add behavior to existing types rather than creating utility classes with static methods.
Coroutines: prefer coroutines with Dispatchers.IO for background work over raw thread pools where new code allows it.
@JvmStatic and @JvmField: annotate members of object classes that are called from Java with @JvmStatic so they compile to static methods.

JVM target is set in app/build.gradle.kts:

kotlinOptions {
  jvmTarget = libs.versions.kotlinJvmTarget.get()
  freeCompilerArgs = listOf("-Xjvm-default=all")
}

Java conventions

Existing code in org.thoughtcrime.securesms is largely Java. When modifying Java files:

Follow the existing code style in the file you are editing.
Prefer annotating parameters and return types with @NonNull / @Nullable.
Use @VisibleForTesting when relaxing access modifiers for test purposes.
Do not introduce new Java files for new features — write Kotlin instead.

Import organization

ktlint enforces import ordering automatically. Do not manually reorder imports; running ./gradlew format will sort them correctly. The general order after formatting is:

Android imports
Third-party library imports
org.signal.* imports
org.thoughtcrime.securesms.* imports
org.whispersystems.* imports

Wildcard imports are not allowed.

Logging

Signal uses a custom logging wrapper. Do not use android.util.Log directly.

// Correct
Log.d(TAG, "Message sent successfully")

// Wrong — will fail the LogNotSignal lint check
android.util.Log.d(TAG, "Message sent successfully")

The custom lint rules LogNotSignal, LogNotAppSignal, and LogTagInlined enforce this at build time and are set to error severity in lint.xml.

Lint rules

The project’s lint.xml configures severity overrides for Android lint checks. Key rules to be aware of:

StopShip (fatal)

Any STOPSHIP comment in a .kt, .kts, .java, or .xml file will cause both the checkStopship Gradle task and lint to fail. Do not leave STOPSHIP markers in code you intend to merge.

HardcodedText (error)

All user-visible strings must be defined in string resources. Hardcoded text in layouts fails lint.

LogNotSignal / LogNotAppSignal / LogTagInlined (error)

Direct use of android.util.Log or inlined log tags is an error. Use Signal’s logging utilities and declare a private static final String TAG (Java) or private val TAG (Kotlin) constant.

StringFormatMatches (error)

Mismatched format string arguments cause runtime crashes. This check is set to error to catch them at build time.

MissingTranslation (ignore)

Missing translations are expected during development — the excludeNonTranslatables task removes untranslated strings from non-English resource files before release.

RestrictedApi (error)

Usage of restricted APIs is an error with narrow path-based exceptions for legacy files. New code must not use restricted APIs.

Running lint

# Lint the main app (play + prod + release variant)
./gradlew lintPlayProdRelease

# Run the full QA suite (lint + tests + format check + stopship)
./gradlew qa

Run ./gradlew qa locally before opening a pull request. It mirrors the checks that run in CI.

Development

Internals

Running the formatter

Setting up lefthook

Installing lefthook

Kotlin conventions

Java conventions

Import organization

Logging

Lint rules

Running lint

​Running the formatter

​Setting up lefthook

​Installing lefthook

​Kotlin conventions

​Java conventions

​Import organization

​Logging

​Lint rules

​Running lint

Running the formatter

Setting up lefthook

Installing lefthook

Kotlin conventions

Java conventions

Import organization

Logging

Lint rules

Running lint