Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

docs: clarify contribution workflow for deployment forks

tianma-if1eab7d21eaf9
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..44e078ad
--- /dev/null
+++ b/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.
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
new file mode 100644
index 00000000..944f1185
--- /dev/null
+++ b/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`,并自行维护与上游的合并。使用独立分支贡献代码时不需要设置这个变量。
diff --git a/README.md b/README.md
index a5b792d0..8d8b64f6 100644
--- a/README.md
+++ b/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
diff --git a/README.zh-CN.md b/README.zh-CN.md
index b377b4af..e60b2aa1 100644
--- a/README.zh-CN.md
+++ b/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。
### 微信交流群