lawnchair/CONTRIBUTING.md

Lawnchair contributing guidelines

Welcome to the Lawnchair project. We appreciate your interest in contributing. For questions, feel free to reach out on Telegram or Discord.

No-code contributions

Bug reports and feature requests

Tip

Use the Lawnchair Nightly builds when reporting bugs, as your issue may have already been fixed.

Warning

For security vulnerability, please do not open an issue. Instead, follow the instructions in our Security Policy.

• For bug reports, please be as detailed as possible and provide clear steps to reproduce the issue.
• For feature requests, clearly describe the feature and its potential benefits.

Please be civil, as outlined in our Code of Conduct.

Translations

For translations, please visit Lawnchair on Crowdin.

Contributing code

Getting started

1. Clone the repository with the --recursive flag to include the project's submodules.

   git clone --recursive https://github.com/LawnchairLauncher/lawnchair.git
   

2. Open the project in Android Studio.
3. Select the lawnWithQuickstepGithubDebug build variant.

If you encounter errors with modules that ends with lib suffix like iconloaderlib or searchuilib, run git submodule update --init --recursive.

Here are some contribution tips to help you get started:

• Always make sure that you're up-to-date with Lawnchair by setting your base branch to 16-dev.
• Make sure your code is logical and well-formatted. If using Kotlin, see “Coding conventions” in the Kotlin documentation;
• The lawnchair package houses Lawnchair’s own code, whereas the src package includes a clone of the Launcher3 codebase with modifications. Generally, place new files in the former, keeping changes to the latter to a minimum.

Additional documentation

• Lawnchair roadmap
• Lawnchair verification
• The Lawnchair Wiki
• Lawnchair Visual Guidelines
• Lawnchair Quickstep Compat Library
• Lawnchair Preferences Components
• Lawnchair Platform Frameworks Library SystemUI
• SystemUI Module
  • ViewCapture
  • Common
• Prebuilt Library

Development workflow

We use a tiered workflow to balance development speed with stability. The process for merging a change depends on its complexity and risk. All PRs should target the 16-dev branch.

Tier	Definition	Examples	Protocol
Trivial changes	Changes with zero risk of functional regression.	Fixing typos in comments or UI text (docs, fix), simple code style fixes (style).	Commit directly to the active branch.
Simple, self-contained work	Changes that are functionally isolated and have a very low risk of side effects.	Most single-file bug fixes, minor UX polish (padding, colors).	1. Create a Pull Request. 2. Assign a reviewer. 3. Enable "Auto-merge" on the PR. It will merge automatically after CI passes and a reviewer approves.
Medium complexity features	New features or changes that affect multiple components but are not deeply architectural.	A new settings screen, a new drawer search provider	1. Create a detailed Pull Request. 2. Assign the core team for review.
Major architectural changes	High-risk, complex changes that affect the core foundation of the app.	Android version rebase	1. Create a very detailed Pull Request. 2. Mandatory Review: You must wait for at least one formal approval from a key team member before merging. The "Merge on Silence" rule does not apply.

Commit message convention

We follow the Conventional Commits specification.

• Format: type(scope): subject
• Example: feat(settings): Add toggle for new feature
• Allowed Types: feat, fix, style, refactor, perf, docs, test, chore.

Versioning scheme

Lawnchair’s version code is composed of five parts, separated by underscores:

1. Android major version
2. Android minor version
3. Lawnchair development stage
4. Lawnchair development version
5. Revision/Release number

Lawnchair development stage

This table show list of development stages in use by Lawnchair:

Stage	Denote
Development	00
Alpha	01
Beta	02
Release Candidate	03
Release	04

String naming

Strings names in strings.xml should follow this format:

Type	Format	Example usage	Actual string	Other information
Generic word	$1	disagree_or_agree	Disagree or agree	Should only be used if it doesn't fit the below categories
Action	$1_action	apply_action	Apply	Any generic action verb can fit here
Preference or popup label Preference headers	$1_label	folders_label	Folders
Preference or popup description	$1_description	folders_description	Row and column count
Preference choice	$1_choice	off_choice	Off
Feature string	(feature_name)_$1	colorpicker_hsb	HSB	Feature strings are strings that are confined to a specific feature. Examples include the gesture and color picker.
Launcher string	$1_launcher	device_contacts_launcher	Contacts from device	Strings that are specific to the Launcher area

Updating locally stored font listing

Lawnchair uses a locally stored JSON file (google_fonts.json) to list available fonts from Google Fonts. This file should be updated periodically or before release to include the latest fonts.

To update Lawnchair’s font listing, follow these steps:

1. Get a Google Fonts Developer API key.
2. Download the JSON file from https://www.googleapis.com/webfonts/v1/webfonts?key=API_KEY, replacing API_KEY with the API key from step 1.
3. Replace the content of google_fonts.json with the API response.

Writing or updating Lawnchair documentation

Lawnchair’s documentations are written in Markdown and follow a style guides from Google developer documentation style guide.