From a567666c79346457c7a8c66b96f2d44cc8b4550d Mon Sep 17 00:00:00 2001 From: fullex <106392080+0xfullex@users.noreply.github.com> Date: Sat, 5 Jul 2025 17:19:25 +0800 Subject: [PATCH] docs: add `testplan` md (#7854) --- CONTRIBUTING.md | 6 ++- README.md | 2 +- docs/CONTRIBUTING.zh.md | 12 +++-- docs/README.zh.md | 2 +- docs/branching-strategy-en.md | 2 + docs/branching-strategy-zh.md | 2 + docs/testplan-en.md | 99 +++++++++++++++++++++++++++++++++++ docs/testplan-zh.md | 99 +++++++++++++++++++++++++++++++++++ 8 files changed, 217 insertions(+), 7 deletions(-) create mode 100644 docs/testplan-en.md create mode 100644 docs/testplan-zh.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9338bc035d..408057252b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -[中文](./docs/CONTRIBUTING.zh.md) | [English](./CONTRIBUTING.md) +[中文](docs/CONTRIBUTING.zh.md) | [English](CONTRIBUTING.md) # Cherry Studio Contributor Guide @@ -58,6 +58,10 @@ git commit --signoff -m "Your commit message" Maintainers are here to help you implement your use case within a reasonable timeframe. They will do their best to review your code and provide constructive feedback promptly. However, if you get stuck during the review process or feel your Pull Request is not receiving the attention it deserves, please contact us via comments in the Issue or through the [Community](README.md#-community). +### Participating in the Test Plan + +The Test Plan aims to provide users with a more stable application experience and faster iteration speed. For details, please refer to the [Test Plan](docs/testplan-en.md). + ### Other Suggestions - **Contact Developers**: Before submitting a PR, you can contact the developers first to discuss or get help. diff --git a/README.md b/README.md index 097f0b5756..ee33521ede 100644 --- a/README.md +++ b/README.md @@ -182,7 +182,7 @@ Refer to the [Branching Strategy](docs/branching-strategy-en.md) for contributio 3. **Submit Changes**: Commit and push your changes. 4. **Open a Pull Request**: Describe your changes and reasons. -For more detailed guidelines, please refer to our [Contributing Guide](./CONTRIBUTING.md). +For more detailed guidelines, please refer to our [Contributing Guide](CONTRIBUTING.md). Thank you for your support and contributions! diff --git a/docs/CONTRIBUTING.zh.md b/docs/CONTRIBUTING.zh.md index 30b1983d18..7574990cd4 100644 --- a/docs/CONTRIBUTING.zh.md +++ b/docs/CONTRIBUTING.zh.md @@ -1,6 +1,6 @@ # Cherry Studio 贡献者指南 -[**English**](../CONTRIBUTING.md) | [**中文**](./CONTRIBUTING.zh.md) +[**English**](../CONTRIBUTING.md) | [**中文**](CONTRIBUTING.zh.md) 欢迎来到 Cherry Studio 的贡献者社区！我们致力于将 Cherry Studio 打造成一个长期提供价值的项目，并希望邀请更多的开发者加入我们的行列。无论您是经验丰富的开发者还是刚刚起步的初学者，您的贡献都将帮助我们更好地服务用户，提升软件质量。 @@ -24,7 +24,7 @@ ## 开始之前 -请确保阅读了[行为准则](CODE_OF_CONDUCT.md)和[LICENSE](LICENSE)。 +请确保阅读了[行为准则](../CODE_OF_CONDUCT.md)和[LICENSE](../LICENSE)。 ## 开始贡献 @@ -32,7 +32,7 @@ ### 测试 -未经测试的功能等同于不存在。为确保代码真正有效，应通过单元测试和功能测试覆盖相关流程。因此，在考虑贡献时，也请考虑可测试性。所有测试均可本地运行，无需依赖 CI。请参阅[开发者指南](docs/dev.md#test)中的“Test”部分。 +未经测试的功能等同于不存在。为确保代码真正有效，应通过单元测试和功能测试覆盖相关流程。因此，在考虑贡献时，也请考虑可测试性。所有测试均可本地运行，无需依赖 CI。请参阅[开发者指南](dev.md#test)中的“Test”部分。 ### 拉取请求的自动化测试 @@ -60,7 +60,11 @@ git commit --signoff -m "Your commit message" ### 获取代码审查/合并 -维护者在此帮助您在合理时间内实现您的用例。他们会尽力在合理时间内审查您的代码并提供建设性反馈。但如果您在审查过程中受阻，或认为您的 Pull Request 未得到应有的关注，请通过 Issue 中的评论或者[社群](README.md#-community)联系我们 +维护者在此帮助您在合理时间内实现您的用例。他们会尽力在合理时间内审查您的代码并提供建设性反馈。但如果您在审查过程中受阻，或认为您的 Pull Request 未得到应有的关注，请通过 Issue 中的评论或者[社群](README.zh.md#-community)联系我们 + +### 参与测试计划 + +测试计划旨在为用户提供更稳定的应用体验和更快的迭代速度，详细情况请参阅[测试计划](testplan-zh.md)。 ### 其他建议 diff --git a/docs/README.zh.md b/docs/README.zh.md index 7c1cccaa1f..774db66627 100644 --- a/docs/README.zh.md +++ b/docs/README.zh.md @@ -190,7 +190,7 @@ https://docs.cherry-ai.com 3. **提交更改**：提交并推送您的更改 4. **打开 Pull Request**：描述您的更改和原因 -有关更详细的指南，请参阅我们的 [贡献指南](./CONTRIBUTING.zh.md) +有关更详细的指南，请参阅我们的 [贡献指南](CONTRIBUTING.zh.md) 感谢您的支持和贡献！ diff --git a/docs/branching-strategy-en.md b/docs/branching-strategy-en.md index f3b7ddf508..8e646249ad 100644 --- a/docs/branching-strategy-en.md +++ b/docs/branching-strategy-en.md @@ -16,6 +16,8 @@ Cherry Studio implements a structured branching strategy to maintain code qualit - Only accepts documentation updates and bug fixes - Thoroughly tested before production deployment +For details about the `testplan` branch used in the Test Plan, please refer to the [Test Plan](testplan-en.md). + ## Contributing Branches When contributing to Cherry Studio, please follow these guidelines: diff --git a/docs/branching-strategy-zh.md b/docs/branching-strategy-zh.md index b1379537a5..36b7ca263d 100644 --- a/docs/branching-strategy-zh.md +++ b/docs/branching-strategy-zh.md @@ -16,6 +16,8 @@ Cherry Studio 采用结构化的分支策略来维护代码质量并简化开发 - 只接受文档更新和 bug 修复 - 经过完整测试后可以发布到生产环境 +关于测试计划所使用的`testplan`分支，请查阅[测试计划](testplan-zh.md)。 + ## 贡献分支 在为 Cherry Studio 贡献代码时，请遵循以下准则： diff --git a/docs/testplan-en.md b/docs/testplan-en.md new file mode 100644 index 0000000000..0f7cd41473 --- /dev/null +++ b/docs/testplan-en.md @@ -0,0 +1,99 @@ +# Test Plan + +To provide users with a more stable application experience and faster iteration speed, Cherry Studio has launched the "Test Plan". + +## User Guide + +The Test Plan is divided into the RC channel and the Beta channel, with the following differences: + +- **RC (Release Candidate)**: The features are stable, with fewer bugs, and it is close to the official release. +- **Beta**: Features may change at any time, and there may be more bugs, but users can experience future features earlier. + +Users can enable the "Test Plan" and select the version channel in the software's `Settings` > `About`. Please note that the versions in the "Test Plan" cannot guarantee data consistency, so be sure to back up your data before using them. + +Users are welcome to submit issues or provide feedback through other channels for any bugs encountered during testing. Your feedback is very important to us. + +## Developer Guide + +### Participating in the Test Plan + +Developers should submit `PRs` according to the [Contributor Guide](../CONTRIBUTING.md) (and ensure the target branch is `main`). The repository maintainers will evaluate whether the `PR` should be included in the Test Plan based on factors such as the impact of the feature on the application, its importance, and whether broader testing is needed. + +If the `PR` is added to the Test Plan, the repository maintainers will: + +- Notify the `PR` submitter. +- Set the PR to `draft` status (to avoid accidental merging into `main` before testing is complete). +- Set the `milestone` to the specific Test Plan version. +- Modify the `PR` title. + +During participation in the Test Plan, `PR` submitters should: + +- Keep the `PR` branch synchronized with the latest `main` (i.e., the `PR` branch should always be based on the latest `main` code). +- Ensure the `PR` branch is conflict-free. +- Actively respond to comments & reviews and fix bugs. +- Enable maintainers to modify the `PR` branch to allow for bug fixes at any time. + +Inclusion in the Test Plan does not guarantee the final merging of the `PR`. It may be shelved due to immature features or poor testing feedback. + +### Test Plan Lead + +A maintainer will be assigned as the lead for a specific version (e.g., `1.5.0-rc`). The responsibilities of the Test Plan lead include: + +- Determining whether a `PR` meets the Test Plan requirements and deciding whether it should be included in the current Test Plan. +- Modifying the status of `PRs` added to the Test Plan and communicating relevant matters with the `PR` submitter. +- Before the Test Plan release, merging the branches of `PRs` added to the Test Plan (using squash merge) into the corresponding version branch of `testplan` and resolving conflicts. +- Ensuring the `testplan` branch is synchronized with the latest `main`. +- Overseeing the Test Plan release. + +## In-Depth Understanding + +### About `PRs` + +A `PR` is a collection of a specific branch (and commits), comments, reviews, and other information, and it is the **smallest management unit** of the Test Plan. + +Compared to submitting all features to a single branch, the Test Plan manages features through `PRs`, which offers greater flexibility and efficiency: + +- Features can be added or removed between different versions of the Test Plan without cumbersome `revert` operations. +- Clear feature boundaries and responsibilities are established. Bug fixes are completed within their respective `PRs`, isolating cross-impact and better tracking progress. +- The `PR` submitter is responsible for resolving conflicts with the latest `main`. The Test Plan lead is responsible for resolving conflicts between `PR` branches. However, since features added to the Test Plan are relatively independent (in other words, if a feature has broad implications, it should be independently included in the Test Plan), conflicts are generally few or simple. + +### The `testplan` Branch + +The `testplan` branch is a **temporary** branch used for Test Plan releases. + +Note: + +- **Do not develop based on this branch**. It may change or even be deleted at any time, and there is no guarantee of commit completeness or order. +- **Do not submit `commits` or `PRs` to this branch**, as they will not be retained. +- The `testplan` branch is always based on the latest `main` branch (not on a released version), with features added on top. + +#### RC Branch + +Branch name: `testplan/rc/x.y.z` + +Used for RC releases, where `x.y.z` is the target version number. Note that whether it is rc.1 or rc.5, as long as the major version number is `x.y.z`, it is completed in this branch. + +Generally, the version number for releases from this branch is named `x.y.z-rc.n`. + +#### Beta Branch + +Branch name: `testplan/beta/x.y.z` + +Used for Beta releases, where `x.y.z` is the target version number. Note that whether it is beta.1 or beta.5, as long as the major version number is `x.y.z`, it is completed in this branch. + +Generally, the version number for releases from this branch is named `x.y.z-beta.n`. + +### Version Rules + +The application version number for the Test Plan is: `x.y.z-CHA.n`, where: + +- `x.y.z` is the conventional version number, referred to here as the **target version number**. +- `CHA` is the channel code (Channel), currently divided into `rc` and `beta`. +- `n` is the release number, starting from `1`. + +Examples of complete version numbers: `1.5.0-rc.3`, `1.5.1-beta.1`, `1.6.0-beta.6`. + +The **target version number** of the Test Plan points to the official version number where these features are expected to be added. For example: + +- `1.5.0-rc.3` means this is a preview of the `1.5.0` official release (the current latest official release is `1.4.9`, and `1.5.0` has not yet been officially released). +- `1.5.1-beta.1` means this is a beta version of the `1.5.1` official release (the current latest official release is `1.5.0`, and `1.5.1` has not yet been officially released). diff --git a/docs/testplan-zh.md b/docs/testplan-zh.md new file mode 100644 index 0000000000..ed4913d4a4 --- /dev/null +++ b/docs/testplan-zh.md @@ -0,0 +1,99 @@ +# 测试计划 + +为了给用户提供更稳定的应用体验，并提供更快的迭代速度，Cherry Studio推出“测试计划”。 + +## 用户指南 + +测试计划分为RC版通道和Beta版通道吗，区别在于： + +- **RC版（预览版）**：RC即Release Candidate，功能已经稳定，BUG较少，接近正式版 +- **Beta版（测试版）**：功能可能随时变化，BUG较多，可以较早体验未来功能 + +用户可以在软件的`设置`-`关于`中，开启“测试计划”并选择版本通道。请注意“测试计划”的版本无法保证数据的一致性，请使用前一定要备份数据。 + +用户在测试过程中发现的BUG，欢迎提交issue或通过其他渠道反馈。用户的反馈对我们非常重要。 + +## 开发者指南 + +### 参与测试计划 + +开发者按照[贡献者指南](CONTRIBUTING.zh.md)要求正常提交`PR`（并注意提交target为`main`）。仓库维护者会综合考虑（例如该功能对应用的影响程度，功能的重要性，是否需要更广泛的测试等），决定该`PR`是否应加入测试计划。 + +若该`PR`加入测试计划，仓库维护者会做如下操作： + +- 通知`PR`提交人 +- 设置PR为`draft`状态（避免在测试完成前意外并入`main`） +- `milestone`设置为具体测试计划版本 +- 修改`PR`标题 + +`PR`提交人在参与测试计划过程中，应做到： + +- 保持`PR`分支与最新`main`同步（即`PR`分支总是应基于最新`main`代码） +- 保持`PR`分支为无冲突状态 +- 积极响应 comments & reviews，修复bug +- 开启维护者可以修改`PR`分支的权限，以便维护者能随时修改BUG + +加入测试计划并不保证`PR`的最终合并，也有可能由于功能不成熟或测试反馈不佳而搁置 + +### 测试计划负责人 + +某个维护者会被指定为某个版本期间（例如`1.5.0-rc`）的测试计划负责人。测试计划负责人的工作为： + +- 判断某个`PR`是否符合测试计划要求，并决定是否应合入当期测试计划 +- 修改加入测试计划的`PR`状态，并与`PR`提交人沟通相关事宜 +- 在测试计划发版前，将加入测试计划的`PR`分支逐一合并（采用squash merge）至`testplan`对应版本分支，并解决冲突 +- 保证`testplan`分支与最新`main`同步 +- 负责测试计划发版 + +## 深入理解 + +### 关于`PR` + +`PR`是特定分支（及commits）、comments、reviews等各种信息的集合，也是测试计划的**最小管理单元**。 + +相比将所有功能都提交到某个分支，测试计划通过`PR`来管理功能，这可以带来极大的灵活度和效率： + +- 测试计划的各个版本间，可以随意增减功能，而无需繁琐的`revert`操作 +- 明确了功能边界和负责人，bug修复在各自`PR`中完成，隔离了交叉影响，也能更好观察进度 +- `PR`提交人负责与最新`main`之间的冲突；测试计划负责人负责各`PR`分支之间的冲突，但因加入测试计划的各功能相对比较独立（话句话说，如果功能牵涉较广，则应独立上测试计划），冲突一般比较少或简单。 + +### `testplan`分支 + +`testplan`分支是用于测试计划发版所用的**临时**分支。 + +注意： + +- **请勿基于该分支开发**。该分支随时会变化甚至删除，且并不保证commit的完整和顺序。 +- **请勿向该分支提交`commit`及`PR`**，将不会得到保留 +- `testplan`分支总是基于最新`main`分支（而不是基于已发布版本），在其之上添加功能 + +#### RC版分支 + +分支名称：`testplan/rc/x.y.z` + +用于RC版的发版，x.y.z为目标版本号，注意无论是rc.1还是rc.5，只要主版本号为x.y.z，都在该分支完成。 + +一般而言，该分支发版的版本号命名为`x.y.z-rc.n` + +#### Beta版分支 + +分支名称：`testplan/beta/x.y.z` + +用于Beta版的发版，x.y.z为目标版本号，注意无论是beta.1还是beta.5，只要主版本号为x.y.z，都在该分支完成。 + +一般而言，该分支发版的版本号命名为`x.y.z-beta.n` + +### 版本规则 + +测试计划的应用版本号为：`x.y.z-CHA.n`，其中： + +- `x.y.z`为一般意义上的版本号，在这里称为**目标版本号** +- `CHA`为通道号（Channel），现在分为`rc`和`beta` +- `n`为发版编号，从`1`计数 + +完整的版本号举例：`1.5.0-rc.3`、`1.5.1-beta.1`、`1.6.0-beta.6` + +测试计划的**目标版本号**指向希望添加这些功能的正式版版本号。例如： + +- `1.5.0-rc.3`是指，这是`1.5.0`正式版的预览版（当前最新正式版是`1.4.9`，而`1.5.0`正式版还未发布） +- `1.5.1-beta.1`是指，这是`1.5.1`正式版的测试版（当前最新正式版是`1.5.0`，而`1.5.1`正式版还未发布）