Contribute Code

Code contributions start with a clear problem. Before fixing a bug, make sure it can be reproduced; before adding a feature, explain the user scenario and expected behavior. For larger changes, it is recommended to align on the direction first in a GitHub Issue or Discussion.

One contribution should solve only one clear problem; complete local verification first, then submit for review.

Before you start

Cherry Studio repository

Source code, README, and development entry points

GitHub Issues

Bugs, feature requests, and unresolved issues

Contribution guide

Branch, testing, signing, and review requirements

Code of conduct

Boundaries for community collaboration

Good starter tasks can be found from good first issue,help wanted and kind/bug labels. Before you start, indicate in the Issue what you plan to handle to avoid duplicate effort from multiple people.

How to choose a branch

Most current features, fixes, refactors, and optimizations are submitted to main. If an Issue, maintainer note, or contribution guide specifies another target branch, follow the project's current instructions; do not judge based only on old tutorials.

Do not determine the target branch from old tutorials. Before creating a PR, check the repository's current contribution guide and PR template again; if the branch strategy has changed, follow what the repository says.

Situations suitable for contributing code

Situation	Recommended approach
Issues that can be reproduced reliably	Submit the minimal fix and corresponding checks first
Small features with clear scope	Confirm the requirements and target branch before starting implementation
Involves data migration, permissions, or architecture	Align on the solution first in an Issue or Discussion
Only needs updates to instructions or screenshots	Go through [contribution docs]; do not mix it into a code PR

One PR should solve only one clear problem. If a change includes features, refactoring, and unrelated formatting all at once, it is hard for reviewers to judge the risk, and it is also harder to roll back.

Submission process

1

1. Fork and create a branch

Create a clearly scoped working branch from the correct target branch. One PR should address only one topic, without mixing in incidental refactoring or formatting adjustments.

2

2. Prepare the development environment

Follow the repository [Developer Guide] to install the specified versions of Node.js and pnpm, then run pnpm install. Before making changes, run the existing checks related to the target module to confirm the baseline is working.

3

3. Make changes and verify

Bug fixes should include tests that reproduce the problem; new features should cover key paths and failure scenarios. Before submitting, run the formatting, linting, testing, and build checks required by the repository.

4

4. Commit and sign off

Write the commit message clearly with the change type and module, and use git commit --signoff to add a DCO sign-off. The sign-off indicates that you have the right to submit this content under the project's license.

5

5. Create a PR

Fill in the template with the before-and-after changes, the reasons for choosing this approach, trade-offs and alternatives, breaking changes, verification method, and release note. Changes that still need discussion can first be created as a Draft PR.

After submitting the PR

A new contributor's PR will initially have needs-ok-to-test, and automated tests will not start immediately. After a repository member confirms it, they will use /ok-to-test to start the pipeline. Draft PRs are not assigned regular reviews and also skip automated tests; once ready, mark them as Ready for review.

Review comments should be addressed with new commits, preserving the discussion context. When design disagreements arise, first return to the user problem and verifiable behavior; do not make broad rewrites to avoid a local issue.

Self-check before submitting

• Target branch is correct;
• The scope of the change matches the Issue/PR description;
• New behavior has tests or repeatable manual verification steps;
• User-visible changes have corresponding documentation updates;
• Data migration, upgrades, and compatibility have been considered;
• No API keys, real user data, or debug files have been committed;
• The commit is signed, and the release note meets the template requirements.

Do small changes also need an Issue?

Spelling fixes and obvious small fixes can be submitted directly; when it involves product behavior, architecture, or a larger amount of work, opening an Issue first makes it easier to confirm the direction. Whether an Issue is required depends on the repository's current maintenance rules.

Why didn't CI run automatically?

First confirm the PR is not a Draft. New contributors' PRs require a repository member /ok-to-test, upon seeing needs-ok-to-test just wait patiently for confirmation in the PR.