> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/en-us/contribution/code.md).

# 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.

<figure><img src="/files/6e0cff6a698399bfb91e8ca68e8955bbd950ee70" alt="从说明问题、最小改动、本地验证到提交评审和合并的贡献流程图"><figcaption><p>One contribution should solve only one clear problem; complete local verification first, then submit for review.</p></figcaption></figure>

## Before you start

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Cherry Studio repository</strong></td><td>Source code, README, and development entry points</td><td><a href="https://github.com/CherryHQ/cherry-studio">https://github.com/CherryHQ/cherry-studio</a></td></tr><tr><td><strong>GitHub Issues</strong></td><td>Bugs, feature requests, and unresolved issues</td><td><a href="https://github.com/CherryHQ/cherry-studio/issues">https://github.com/CherryHQ/cherry-studio/issues</a></td></tr><tr><td><strong>Contribution guide</strong></td><td>Branch, testing, signing, and review requirements</td><td><a href="https://github.com/CherryHQ/cherry-studio/blob/main/CONTRIBUTING.md">https://github.com/CherryHQ/cherry-studio/blob/main/CONTRIBUTING.md</a></td></tr><tr><td><strong>Code of conduct</strong></td><td>Boundaries for community collaboration</td><td><a href="https://github.com/CherryHQ/cherry-studio/blob/main/CODE_OF_CONDUCT.md">https://github.com/CherryHQ/cherry-studio/blob/main/CODE_OF_CONDUCT.md</a></td></tr></tbody></table>

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.

{% hint style="warning" %}
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.
{% endhint %}

## 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             |

{% hint style="info" %}
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.
{% endhint %}

## Submission process

{% stepper %}
{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

## 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.

<details>

<summary>Do small changes also need an Issue?</summary>

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.

</details>

<details>

<summary>Why didn't CI run automatically?</summary>

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.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/en-us/contribution/code.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.