From 0c27b4bd47cd1176af03d09553b4bd361a4894d7 Mon Sep 17 00:00:00 2001
From: MadDogOwner <xiaoran@xrgzs.top>
Date: Sun, 24 Aug 2025 20:13:11 +0800
Subject: [PATCH] docs(contributing): update guidelines (#983)

[skip ci]

* docs(contributing): update guidelines

* docs(contributing): clarify fork

* docs(contributing): sync translation

Co-authored-by: Yinan Qin <39023210+elysia-best@users.noreply.github.com>
Signed-off-by: MadDogOwner <xiaoran@xrgzs.top>

* docs(contributing): add label and cc reminder

* docs(contributing): remove ensure new branch from checklist

* docs(contributing): replace generic GitHub URLs with user-specific ones

* docs(contributing): make branch deletion after PR merge optional

* docs(contributing): keep --recurse-submodules

---------

Signed-off-by: MadDogOwner <xiaoran@xrgzs.top>
Co-authored-by: Yinan Qin <39023210+elysia-best@users.noreply.github.com>
---
 .github/PULL_REQUEST_TEMPLATE.md |  56 ++++++++++++++++
 CONTRIBUTING.md                  | 110 +++++++++++--------------------
 2 files changed, 96 insertions(+), 70 deletions(-)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000..e74e5963
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,56 @@
+<!--
+  Provide a general summary of your changes in the Title above.
+  The PR title must start with `feat(): `, `docs(): `, `fix(): `, `style(): `, or `refactor(): `, `chore(): `. For example: `feat(component): add new feature`.
+  If it spans multiple components, use the main component as the prefix and enumerate in the title, describe in the body.
+-->
+<!--
+  在上方标题中提供您更改的总体摘要。
+  PR 标题需以 `feat(): `, `docs(): `, `fix(): `, `style(): `, `refactor(): `, `chore(): ` 其中之一开头，例如：`feat(component): 新增功能`。
+  如果跨多个组件，请使用主要组件作为前缀，并在标题中枚举、描述中说明。
+-->
+
+## Description / 描述
+
+<!-- Describe your changes in detail -->
+<!-- 详细描述您的更改 -->
+
+## Motivation and Context / 背景
+
+<!-- Why is this change required? What problem does it solve? -->
+<!-- 为什么需要此更改？它解决了什么问题？ -->
+
+<!-- If it fixes an open issue, please link to the issue here. -->
+<!-- 如果修复了一个打开的issue，请在此处链接到该issue -->
+
+Closes #XXXX
+
+<!-- or -->
+<!-- 或者 -->
+
+Relates to #XXXX
+
+## How Has This Been Tested? / 测试
+
+<!-- Please describe in detail how you tested your changes. -->
+<!-- 请详细描述您如何测试更改 -->
+
+## Checklist / 检查清单
+
+<!-- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!-- 检查以下所有要点，并在所有适用的框中打`x` -->
+
+<!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+<!-- 如果您对其中任何一项不确定，请不要犹豫提问。我们会帮助您！ -->
+
+- [ ] I have read the [CONTRIBUTING](https://github.com/OpenListTeam/OpenList/blob/main/CONTRIBUTING.md) document.
+      我已阅读 [CONTRIBUTING](https://github.com/OpenListTeam/OpenList/blob/main/CONTRIBUTING.md) 文档。
+- [ ] I have formatted my code with `go fmt` or [prettier](https://prettier.io/).
+      我已使用 `go fmt` 或 [prettier](https://prettier.io/) 格式化提交的代码。
+- [ ] I have added appropriate labels to this PR (or mentioned needed labels in the description if lacking permissions).
+      我已为此 PR 添加了适当的标签（如无权限或需要的标签不存在，请在描述中说明，管理员将后续处理）。
+- [ ] I have requested review from relevant code authors using the "Request review" feature when applicable.
+      我已在适当情况下使用"Request review"功能请求相关代码作者进行审查。
+- [ ] I have updated the repository accordingly (If it’s needed).
+      我已相应更新了相关仓库（若适用）。
+  - [ ] [OpenList-Frontend](https://github.com/OpenListTeam/OpenList-Frontend) #XXXX
+  - [ ] [OpenList-Docs](https://github.com/OpenListTeam/OpenList-Docs) #XXXX
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c8ce47b2..6064b03c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,106 +2,76 @@
 
 ## Setup your machine
 
-`OpenList` is written in [Go](https://golang.org/) and [React](https://reactjs.org/).
+`OpenList` is written in [Go](https://golang.org/) and [SolidJS](https://www.solidjs.com/).
 
 Prerequisites:
 
 - [git](https://git-scm.com)
-- [Go 1.20+](https://golang.org/doc/install)
+- [Go 1.24+](https://golang.org/doc/install)
 - [gcc](https://gcc.gnu.org/)
 - [nodejs](https://nodejs.org/)
 
-Clone `OpenList` and `OpenList-Frontend` anywhere:
+## Cloning a fork
+
+Fork and clone `OpenList` and `OpenList-Frontend` anywhere:
 
 ```shell
-$ git clone https://github.com/OpenListTeam/OpenList.git
-$ git clone --recurse-submodules https://github.com/OpenListTeam/OpenList-Frontend.git
+$ git clone https://github.com/<your-username>/OpenList.git
+$ git clone --recurse-submodules https://github.com/<your-username>/OpenList-Frontend.git
+```
+
+## Creating a branch
+
+Create a new branch from the `main` branch, with an appropriate name.
+
+```shell
+$ git checkout -b <branch-name>
 ```
-You should switch to the `main` branch for development.
 
 ## Preview your change
+
 ### backend
+
 ```shell
 $ go run main.go
 ```
+
 ### frontend
+
 ```shell
 $ pnpm dev
 ```
 
 ## Add a new driver
+
 Copy `drivers/template` folder and rename it, and follow the comments in it.
 
 ## Create a commit
 
 Commit messages should be well formatted, and to make that "standardized".
 
-### Commit Message Format
-Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
-format that includes a **type**, a **scope** and a **subject**:
+Submit your pull request. For PR titles, follow [Conventional Commits](https://www.conventionalcommits.org).
 
-```
-<type>(<scope>): <subject>
-<BLANK LINE>
-<body>
-<BLANK LINE>
-<footer>
-```
+https://github.com/OpenListTeam/OpenList/issues/376
 
-The **header** is mandatory and the **scope** of the header is optional.
-
-Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier
-to read on GitHub as well as in various git tools.
-
-### Revert
-If the commit reverts a previous commit, it should begin with `revert: `, followed by the header
-of the reverted commit.
-In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit
-being reverted.
-
-### Type
-Must be one of the following:
-
-* **feat**: A new feature
-* **fix**: A bug fix
-* **docs**: Documentation only changes
-* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
-  semi-colons, etc)
-* **refactor**: A code change that neither fixes a bug nor adds a feature
-* **perf**: A code change that improves performance
-* **test**: Adding missing or correcting existing tests
-* **build**: Affects project builds or dependency modifications
-* **revert**: Restore the previous commit
-* **ci**: Continuous integration of related file modifications
-* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
-  generation
-* **release**: Release a new version
-
-### Scope
-The scope could be anything specifying place of the commit change. For example `$location`,
-`$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`, `ngView`, etc...
-
-You can use `*` when the change affects more than a single scope.
-
-### Subject
-The subject contains succinct description of the change:
-
-* use the imperative, present tense: "change" not "changed" nor "changes"
-* don't capitalize first letter
-* no dot (.) at the end
-
-### Body
-Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
-The body should include the motivation for the change and contrast this with previous behavior.
-
-### Footer
-The footer should contain any information about **Breaking Changes** and is also the place to
-[reference GitHub issues that this commit closes](https://help.github.com/articles/closing-issues-via-commit-messages/).
-
-**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines.
-The rest of the commit message is then used for this.
+It's suggested to sign your commits. See: [How to sign commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
 
 ## Submit a pull request
 
-Push your branch to your `openlist` fork and open a pull request against the
-`main` branch.
+Please make sure your code has been formatted with `go fmt` or [prettier](https://prettier.io/) before submitting.
+
+Push your branch to your `openlist` fork and open a pull request against the `main` branch.
+
+## Merge your pull request
+
+Your pull request will be merged after review. Please wait for the maintainer to merge your pull request after review.
+
+At least 1 approving review is required by reviewers with write access. You can also request a review from maintainers.
+
+## Delete your branch
+
+(Optional) After your pull request is merged, you can delete your branch.
+
+---
+
+Thank you for your contribution! Let's make OpenList better together!