Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

docs: define focused pull request contribution guidelines

baiyuze92ea2b53bb45
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..65b1859
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,43 @@
+<!-- Please read CONTRIBUTING.md / 提交前请阅读 CONTRIBUTING.zh-CN.md。
+One PR, one independent goal. Related tests and docs belong in the same PR.
+一个 PR 只处理一个独立目标,相关测试和文档可以一并提交。
+-->
+
+## Purpose / 目的
+
+<!-- What single problem does this solve? Link a related issue if available.
+这次只解决什么问题?有相关 Issue 时请附链接。
+-->
+
+## Changes / 修改范围
+
+<!-- Summarize concrete changes. Move unrelated features or refactors to another PR.
+列出具体修改;无关功能或重构请另开 PR。
+-->
+
+-
+
+## Impact / 影响
+
+<!-- Affected platforms, behavior and compatibility. Add screenshots for UI changes.
+说明受影响的平台、行为和兼容性;界面修改请附截图。
+If this depends on another PR, link it and explain the merge order.
+如依赖其他 PR,请附链接并说明合并顺序。
+-->
+
+## Validation / 验证
+
+<!-- List actual commands or manual steps and their results.
+State relevant platforms not tested; documentation-only changes can use formatting/link checks.
+填写实际执行的命令或手动步骤及结果,注明尚未验证的相关平台。
+纯文档修改可以填写格式和链接检查结果。
+-->
+
+-
+
+## Checklist / 提交前确认
+
+- [ ] This PR has one independent goal. / 本 PR 只有一个独立目标。
+- [ ] Unrelated changes are in separate PRs. / 无关改动已拆分。
+- [ ] Relevant tests and docs are updated where needed. / 已按需补充相关测试和文档。
+- [ ] Validation results and coverage limits are described above. / 已说明验证结果与未覆盖范围。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..b41d5ec
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing to PasteFerry
+
+[简体中文](CONTRIBUTING.zh-CN.md)
+
+Thank you for contributing. Keep each pull request focused on one independent
+goal so it can be reviewed, tested and reverted on its own.
+
+## One goal per pull request
+
+- Submit one feature, one bug fix or one focused documentation improvement per
+ PR. Include the tests and documentation directly needed for that change.
+- Put unrelated features, refactors, dependency upgrades and incidental fixes
+ in separate PRs, even when they touch the same files.
+- There is no fixed limit on commits or changed lines. Scope and reviewability
+ matter more than the commit count.
+- PRs combining independent changes will be asked to split before review
+ continues. Please do not keep adding new features to a PR already under review.
+
+For example, a CLI version command, JSON query support and a Homebrew package
+are separate goals. A feature's implementation, regression test and usage
+documentation belong together. Fixing the same bug across several platforms
+can also be one coherent PR.
+
+## Discuss larger changes first
+
+Before implementing a substantial feature, architecture change, new runtime
+dependency or installation method, open an
+[issue](https://github.com/baiyuze/pasteferry/issues) to discuss the problem,
+proposed scope and approach with the maintainers.
+
+Start a separate branch from the latest `main` for each independent change.
+If a PR depends on another PR, link it and explain the dependency and intended
+merge order. Keep unfinished work as a Draft PR.
+
+## Describe the change and its validation
+
+Use the PR template and provide:
+
+1. The single problem or goal, with a related issue link when available.
+2. The concrete changes and affected platforms or behavior.
+3. The checks you actually ran, their results and manual reproduction or
+ verification steps. State which relevant platforms were not tested.
+4. Screenshots or a short recording for visible UI changes, plus any
+ compatibility or migration implications.
+
+Run checks appropriate to the change and address relevant CI failures before
+requesting review. Add or update regression tests for bug fixes where practical;
+documentation-only changes can be checked by reviewing formatting and links.
+Build instructions are in [Building from source](guide/building.md).
+
+During review, keep follow-up commits within the original goal. Submit new
+ideas in another issue or PR. If splitting is requested, keep the original
+discussion linked from the replacement PRs.
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
new file mode 100644
index 0000000..844d015
--- /dev/null
+++ b/CONTRIBUTING.zh-CN.md
@@ -0,0 +1,34 @@
+# 为隔空贴贡献代码
+
+[English](CONTRIBUTING.md)
+
+感谢参与项目。每个 PR 请只处理一个独立目标,让它能够单独审查、测试和回退。
+
+## 一个 PR,一个目标
+
+- 每个 PR 只增加一项独立功能、修复一个问题,或完成一项明确的文档改进。与该改动直接相关的测试和文档应放在同一个 PR 中。
+- 其他功能、无关重构、依赖升级和顺手修复请分别提交,即使它们修改了同一个文件。
+- 不硬性限制 commit 数量或修改行数,重点是范围清楚、便于审查。
+- 混入多项独立改动的 PR 会被要求拆分后再继续审查。已经进入审查的 PR,请不要持续加入新功能。
+
+例如:CLI 版本查询、JSON 查询支持、Homebrew 安装方式应分别提交;某项功能的实现、回归测试和使用文档可以放在一起。同一个问题在多个平台上的修复,也可以作为一个完整 PR。
+
+## 较大改动先讨论
+
+较大的新功能、架构调整、新增运行时依赖或安装方式,请先开
+[Issue](https://github.com/baiyuze/pasteferry/issues),说明要解决的问题、预计范围和方案,与维护者讨论后再实现。
+
+每项独立改动从最新的 `main` 创建单独分支。如果依赖其他 PR,请附上链接,说明依赖关系和合并顺序。尚未完成的工作请标记为 Draft。
+
+## 写清改动和验证结果
+
+请使用 PR 模板,说明以下内容:
+
+1. 这次只解决什么问题或实现什么目标;有相关 Issue 时附上链接。
+2. 具体修改了什么,影响哪些平台或现有行为。
+3. 实际执行过的检查、结果和手动复现或验证步骤;相关平台尚未测试的,请明确注明。
+4. 界面变化的截图或短录屏,以及兼容性和迁移方面的影响。
+
+请运行与改动相关的检查,在请求审查前处理相关 CI 失败。修复问题时,在可行的情况下补充或更新回归测试;纯文档修改可以通过检查格式和链接验证。构建方法见[从源码构建](guide/building.zh-CN.md)。
+
+审查期间的后续提交应围绕原定目标。新想法请另开 Issue 或 PR。如果被要求拆分,请在拆分后的 PR 中链接原来的讨论。
diff --git a/README.md b/README.md
index 7a056c6..38ca3c1 100644
--- a/README.md
+++ b/README.md
@@ -209,6 +209,12 @@ See the [CLI JSON reference](design/cli-json.md) for the supported read-only que
- [Privacy](PRIVACY.md), [security](SECURITY.md), [official service protocol](design/official-gateway.md)
- [Changelog](CHANGELOG.md)
+## Contributing
+
+Please read the [contribution guidelines](CONTRIBUTING.md) before opening a pull request.
+Keep each PR focused on one independent goal, including its related tests and documentation.
+Discuss larger changes in an issue first and describe the checks you actually ran in the PR template.
+
## Support the project
PasteFerry is free and open source. If it helps you, **a ⭐ star** is the best support and helps others who need it find it. Questions and ideas are welcome as [issues](https://github.com/baiyuze/pasteferry/issues).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 44f3152..2cf0d71 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -198,6 +198,11 @@ JSON 模式支持上述只读查询,格式及示例见 [CLI JSON 接口](desig
- [隐私说明](PRIVACY.md)、[安全说明](SECURITY.md)、[「服务」的公开协议](design/official-gateway.md)
- [更新记录](CHANGELOG.md)
+## 参与贡献
+
+提交 PR 前请阅读[贡献规范](CONTRIBUTING.zh-CN.md)。每个 PR 只处理一个独立目标,相关测试和文档可以一并提交。
+较大改动请先开 Issue 讨论,并在 PR 模板中写清修改范围和实际验证结果。
+
## 支持一下
隔空贴免费开源。如果它帮到了你,**点一个 ⭐ Star** 就是最好的支持,也能让更多需要它的人看到。遇到问题或有想法,欢迎[提 issue](https://github.com/baiyuze/pasteferry/issues)。