docs: clarify contribution workflow for deployment forks

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to EdgeEver
+
+[简体中文](CONTRIBUTING.zh-CN.md) | English
+
+Thank you for contributing to EdgeEver. A Fork used for Cloudflare deployment can also be used for code contributions, but deployment and development must use different branches.
+
+## Keep the deployment branch separate
+
+If your Fork is used to deploy EdgeEver:
+
+- Treat the Fork's `main` as a deployment-only branch managed by **Update deployed EdgeEver**.
+- Do not develop features directly on that `main` branch.
+- Do not use GitHub **Sync fork** to update the deployment `main` during routine development or deployment updates.
+- Create each contribution branch directly from the official repository's latest `upstream/main`.
+
+The deployment workflow only updates the Fork's `main`. It does not modify your contribution branches.
+
+## Create a contribution branch
+
+Clone your Fork and add the official repository as `upstream`:
+
+```sh
+git clone https://github.com/<your-account>/edgeever.git
+cd edgeever
+git remote add upstream https://github.com/tianma-if/edgeever.git
+git fetch upstream
+```
+
+Create a new branch from the official latest `main`, not from the deployment branch:
+
+```sh
+git switch -c feat/short-description upstream/main
+```
+
+Make and commit your changes, then push the contribution branch to your Fork:
+
+```sh
+git push -u origin feat/short-description
+```
+
+Open a Pull Request from:
+
+```text
+<your-account>/edgeever:feat/short-description
+    -> tianma-if/edgeever:main
+```
+
+Your Fork's `main` does not need to match the official `main` for this Pull Request. GitHub uses the contribution branch as the Pull Request source.
+
+## Synchronize an in-progress contribution
+
+When the official repository changes, update the contribution branch without touching the deployment `main`:
+
+```sh
+git fetch upstream
+git switch feat/short-description
+git rebase upstream/main
+```
+
+If the branch was already pushed, update it safely with:
+
+```sh
+git push --force-with-lease origin feat/short-description
+```
+
+Resolve any conflicts on the contribution branch. Do not resolve them by synchronizing the deployment `main`.
+
+## Verify your changes
+
+Install dependencies and run the checks relevant to your change. The core validation commands are:
+
+```sh
+bun install
+bun run test
+bun run typecheck
+bun run typecheck:mobile
+bun run build:web
+```
+
+Platform-specific changes may require additional checks.
+
+## Customized deployments
+
+Keeping personal product changes permanently on the deployed `main` is a customized deployment, not the normal contribution workflow. Customized deployments must opt in with `EDGE_EVER_PRESERVE_FORK_CHANGES=true` and maintain their own upstream merges. You do not need this setting when contributing through a separate branch.

CONTRIBUTING.zh-CN.md

@@ -0,0 +1,84 @@
+# 为 EdgeEver 贡献代码
+
+简体中文 | [English](CONTRIBUTING.md)
+
+感谢您为 EdgeEver 贡献代码。用于 Cloudflare 部署的 Fork 也可以提交代码贡献，但部署与开发必须使用不同的分支。
+
+## 将部署分支与贡献分支分开
+
+如果您的 Fork 用于部署 EdgeEver：
+
+- 将 Fork 的 `main` 视为仅用于部署的分支，并交由 **Update deployed EdgeEver** 管理。
+- 不要直接在这个 `main` 分支上开发功能。
+- 日常开发和部署更新时，不要通过 GitHub **Sync fork** 更新部署用的 `main`。
+- 每项代码贡献都应从官方仓库最新的 `upstream/main` 创建独立分支。
+
+部署更新工作流只会更新 Fork 的 `main`，不会修改您的贡献分支。
+
+## 创建贡献分支
+
+克隆您的 Fork，并将官方仓库添加为 `upstream`：
+
+```sh
+git clone https://github.com/<您的账号>/edgeever.git
+cd edgeever
+git remote add upstream https://github.com/tianma-if/edgeever.git
+git fetch upstream
+```
+
+从官方最新的 `main` 创建新分支，不要从部署分支开始开发：
+
+```sh
+git switch -c feat/简短说明 upstream/main
+```
+
+完成修改并提交后，将贡献分支推送到您的 Fork：
+
+```sh
+git push -u origin feat/简短说明
+```
+
+然后创建以下 Pull Request：
+
+```text
+<您的账号>/edgeever:feat/简短说明
+    -> tianma-if/edgeever:main
+```
+
+提交这个 Pull Request 时，您的 Fork `main` 不需要与官方 `main` 保持一致。GitHub 使用的是贡献分支，而不是部署分支。
+
+## 为开发中的贡献同步上游代码
+
+官方仓库有新提交时，直接更新贡献分支，不要改动部署用的 `main`：
+
+```sh
+git fetch upstream
+git switch feat/简短说明
+git rebase upstream/main
+```
+
+如果该分支已经推送过，请安全地更新远端贡献分支：
+
+```sh
+git push --force-with-lease origin feat/简短说明
+```
+
+如有冲突，请在贡献分支中解决，不要通过同步部署用的 `main` 来处理。
+
+## 验证修改
+
+安装依赖并运行与改动相关的检查。核心验证命令包括：
+
+```sh
+bun install
+bun run test
+bun run typecheck
+bun run typecheck:mobile
+bun run build:web
+```
+
+特定平台的改动可能还需要额外检查。
+
+## 定制部署
+
+如果您希望将个人产品改动长期保留在部署用的 `main`，这属于定制部署，而不是普通的代码贡献流程。定制部署需要设置 `EDGE_EVER_PRESERVE_FORK_CHANGES=true`，并自行维护与上游的合并。使用独立分支贡献代码时不需要设置这个变量。

README.md

@@ -148,6 +148,7 @@ On platforms without a native client, EdgeEver can be installed as a PWA using C
 ## Community and Feedback
 
 - Bugs, feature requests, and deployment issues: [GitHub Issues](https://github.com/tianma-if/edgeever/issues)
+- Code contributions: read the [Contribution Guide](CONTRIBUTING.md). If your Fork is also used to deploy EdgeEver, keep its `main` branch deployment-only. Create a separate branch from the official `upstream/main` for synchronization, development, and pull requests; do not develop on or Sync fork the deployment `main`.
 
 ### WeChat Community Group
 

README.zh-CN.md

@@ -145,6 +145,7 @@ macOS App 可从 [GitHub Releases](https://github.com/tianma-if/edgeever/release
 ## 社区与反馈
 
 - Bug、功能建议和部署问题请优先提交 [GitHub Issues](https://github.com/tianma-if/edgeever/issues)，方便后续用户检索和复用解决方案。
+- 贡献代码前请阅读[贡献代码须知](CONTRIBUTING.zh-CN.md)。如果您的 Fork 同时用于部署 EdgeEver，请将 `main` 分支仅用于部署；从官方 `upstream/main` 新建独立分支，在该分支中同步上游、开发并提交 Pull Request，不要在部署用的 `main` 上开发或执行 Sync fork。
 
 ### 微信交流群