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//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 +/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。 ### 微信交流群