Submit an Android pull request

Your change works on your machine. Now it needs a pull request, a review, and a merge. This page covers what reviewers expect, so the review goes smoothly.

• Format and test. Run ./gradlew :build-logic:convention:ktlintFormat ktlintFormat and ./gradlew test. See code style and linting for the other checks.
• Build everything. Shared code ends up in the phone, car, and watch apps. Check that :app, :automotive, and :wear still build.
• Add tests for the behavior you changed. See testing.
• Follow the guidelines: best practices, UI architecture, and Compose and the design system.
• Keep it small. One idea per pull request. Big reworks go behind a WIPFeature flag in small steps, see ship big changes in small steps.
• Read the AI policy. You can use AI tools, but you must understand and be able to explain every line you submit. Pull requests from autonomous agents are closed.

Create the pull request from your fork against main, as described in the GitHub documentation. GitHub fills in the template. Don't delete anything from it, unless the template tells you to, like a section that doesn't apply to your change. Fill out:

• Summary: what you changed, why, and what it means for users. Link related issues.
• Checklist: tests, code style, edge cases, backward compatibility, and the AI policy. Backward-incompatible changes go in the changelog for users, or in the code for developers, depending on who they affect. Also select exactly one of the options that describe how you used AI.
• Screenshots: for UI changes outside the frontend, in light and dark mode.
• Documentation: if your change adds, changes, or removes something users see, open a pull request in the user documentation and link it. Mark the new feature there with <span class='beta'>BETA</span>, until it reaches production. If it changes something developers rely on, like how to build, test, or release the app, the template also asks for a pull request that updates the developer documentation.

If your change adds a feature, visibly changes behavior for users, or breaks something they rely on, add it to the in-app changelog in app/src/main/kotlin/io/homeassistant/companion/android/changelog/ChangelogContent.kt. Small bug fixes don't need their own entry: the standing "Bug fixes and dependency updates" entry covers them.

ChangelogContent.kt holds the entries, grouped in new, improved, and fixed, each with the platforms it applies to. The text of each entry is a string in common/src/main/res/values/strings_changelog.xml, so it gets translated. A screenshot test renders the real changelog, so a changelog change also needs updated screenshot references.

Open a draft when you want early feedback on direction, but the work isn't done. This is also useful when you work on changes to CI itself. Be careful with CI, though: each push runs the full pipeline, which takes a lot of resources. Don't open a pull request, draft or not, before there is something to look at. Push to your fork as often as you like.

If this is your first contribution, a maintainer has to approve each CI run before it starts.

Anyone can review a pull request, and you are welcome to. Even a ten-minute review helps. Not comfortable reviewing code? Install the APK from the pull request, and report what you find: bugs, crashes, or UI and UX feedback. See test a pull request build.

For a merge, a maintainer has to approve. Be patient and kind. Their feedback comes as comments with requested changes, or as questions. Answer questions in your own words, not with AI output.

When you have addressed the feedback and CI is green, ask for another review.

If your branch falls behind main or has conflicts, you can either merge main into your branch and resolve the conflicts, or rebase on it:

• Not reviewed yet: merge or rebase, your choice.
• Already reviewed: merge. A rebase can break existing review comments and lose that feedback.

The repository uses squash and merge, so your branch history doesn't need to be tidy.

Once everything is green and a maintainer approves, they merge it. You don't have to do anything. Your change goes to internal testers right away, and to the beta the next weekend. See releases.

A bot marks a pull request as stale after 30 days without activity, and an issue after 90 days. If nothing happens in the next 7 days, it closes them. Anything labeled under investigation or Help wanted is exempt.