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: clarify contribution scope, validation and attribution

baiyuzef4d9e398d10d
diff --git a/.github/ISSUE_TEMPLATE/feature_proposal.yml b/.github/ISSUE_TEMPLATE/feature_proposal.yml
new file mode 100644
index 0000000..d0cf9c8
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_proposal.yml
@@ -0,0 +1,25 @@
+name: Feature proposal / 功能讨论
+description: Discuss a feature or larger change before implementation. / 实现前讨论新功能或较大改动。
+body:
+ - type: markdown
+ attributes:
+ value: >-
+ Describe the goal and expected scope; a finished implementation is not required.
+ 请说明目标和预计范围,不需要先完成实现。
+ - type: textarea
+ id: problem
+ attributes:
+ label: Problem or goal / 问题与目标
+ description: What would you like to improve, and who would benefit? / 希望解决什么问题,哪些使用者会受益?
+ validations:
+ required: true
+ - type: textarea
+ id: proposal
+ attributes:
+ label: Proposed approach / 拟议方案
+ description: Describe an approach if you have one; it is fine to discuss options first. / 如已有想法,请简述方案;也可以先讨论可行方向。
+ - type: textarea
+ id: scope
+ attributes:
+ label: Expected scope / 预计范围
+ description: Affected platforms or behavior, compatibility concerns, and dependencies on other work, if known. / 如已知,请说明涉及的平台或行为、兼容性影响及对其他改动的依赖。
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 65b1859..da99ad9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -13,6 +13,10 @@ One PR, one independent goal. Related tests and docs belong in the same PR.
<!-- Summarize concrete changes. Move unrelated features or refactors to another PR.
列出具体修改;无关功能或重构请另开 PR。
+Explain supporting refactors or dependency changes needed for this goal.
+如包含完成当前目标所需的重构或依赖调整,请说明关联。
+If this builds on another person's PR or patch, link the source and describe what was reused or adapted.
+如基于他人的 PR 或补丁,请关联来源并说明沿用或调整的内容。
-->
-
@@ -30,6 +34,8 @@ If this depends on another PR, link it and explain the merge order.
<!-- List actual commands or manual steps and their results.
State relevant platforms not tested; documentation-only changes can use formatting/link checks.
填写实际执行的命令或手动步骤及结果,注明尚未验证的相关平台。
+You do not need devices for every platform; describe existing CI or environment blockers separately.
+无需自备全部平台设备;如有既有 CI 故障或环境限制,请单独说明。
纯文档修改可以填写格式和链接检查结果。
-->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b41d5ec..7fce7ef 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,16 +10,22 @@ goal so it can be reviewed, tested and reverted on its own.
- 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.
+ in separate PRs, even when they touch the same files. Supporting refactors or
+ dependency changes needed for the current goal can stay together; explain
+ why they are needed.
- 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.
+- If a PR combines independent goals, maintainers will discuss its scope and
+ how to split it with you. Keep unrelated new features out of 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.
+Changes that can be reviewed, tested and reverted independently are usually
+best submitted separately. For example, an installation improvement and an
+unrelated UI feature usually belong in separate PRs. A feature's implementation,
+regression test and usage documentation belong together. Fixing the same bug
+across several platforms can also be one coherent PR. If a larger change needs
+to stay together to achieve one goal, explain the relationship and discuss the
+scope with the maintainers.
## Discuss larger changes first
@@ -28,6 +34,11 @@ dependency or installation method, open an
[issue](https://github.com/baiyuze/pasteferry/issues) to discuss the problem,
proposed scope and approach with the maintainers.
+The [feature proposal template](https://github.com/baiyuze/pasteferry/issues/new?template=feature_proposal.yml)
+provides a short starting point; you do not need a finished implementation to
+start the discussion. Small, focused fixes and documentation improvements can
+be submitted directly as PRs.
+
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.
@@ -43,11 +54,31 @@ Use the PR template and provide:
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.
+Run checks appropriate to the change and address CI failures introduced by it
+before requesting review. If an existing CI failure or an environment problem
+blocks validation, describe it so it can be investigated together. You do not
+need access to every supported platform: report the checks you could run and
+the coverage limits; CI or maintainers can help with the remaining platforms.
+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.
+
+## Preserve contribution sources
+
+When maintainers adopt part of a PR or reorganize an external contribution,
+they will link the original PR and the resulting commits, and describe what
+was included and what remains outside the change.
+
+Preserve original authorship when retaining a contributor's commits. When
+combining substantial contributed code into a new commit, record appropriate
+credit, such as a `Co-authored-by` trailer using the contributor's supplied
+author information. When an idea is reimplemented, cite the original proposal
+and thank its contributor rather than implying that their commits were merged.
+
+For PRs submitted before these guidelines or a later revision, discuss the
+scope and any proposed split with the contributor. Do not treat a contribution
+as having violated requirements that were introduced after it was submitted.
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
index 844d015..dc123c5 100644
--- a/CONTRIBUTING.zh-CN.md
+++ b/CONTRIBUTING.zh-CN.md
@@ -7,17 +7,19 @@
## 一个 PR,一个目标
- 每个 PR 只增加一项独立功能、修复一个问题,或完成一项明确的文档改进。与该改动直接相关的测试和文档应放在同一个 PR 中。
-- 其他功能、无关重构、依赖升级和顺手修复请分别提交,即使它们修改了同一个文件。
+- 无关的功能、重构、依赖升级和顺手修复请分别提交,即使它们修改了同一个文件。为完成当前目标确有必要的重构或依赖调整可以一并提交,请说明它们的关系。
- 不硬性限制 commit 数量或修改行数,重点是范围清楚、便于审查。
-- 混入多项独立改动的 PR 会被要求拆分后再继续审查。已经进入审查的 PR,请不要持续加入新功能。
+- PR 涉及多个独立目标时,维护者会先与你讨论范围和拆分方式。已经进入审查的 PR,请不要持续加入与原目标无关的新功能。
-例如:CLI 版本查询、JSON 查询支持、Homebrew 安装方式应分别提交;某项功能的实现、回归测试和使用文档可以放在一起。同一个问题在多个平台上的修复,也可以作为一个完整 PR。
+能够独立审查、测试和回退的改动,通常建议分别提交。例如,安装方式的改进与独立的界面功能通常适合拆分;某项功能的实现、回归测试和使用文档应放在一起。同一个问题在多个平台上的修复,也可以作为一个完整 PR。如果较大的改动必须共同完成同一目标,请说明关联,与维护者协商范围。
## 较大改动先讨论
较大的新功能、架构调整、新增运行时依赖或安装方式,请先开
[Issue](https://github.com/baiyuze/pasteferry/issues),说明要解决的问题、预计范围和方案,与维护者讨论后再实现。
+可以使用简短的[功能讨论模板](https://github.com/baiyuze/pasteferry/issues/new?template=feature_proposal.yml),不需要先完成实现才来讨论。小范围的问题修复和文档改进可以直接提交 PR。
+
每项独立改动从最新的 `main` 创建单独分支。如果依赖其他 PR,请附上链接,说明依赖关系和合并顺序。尚未完成的工作请标记为 Draft。
## 写清改动和验证结果
@@ -29,6 +31,14 @@
3. 实际执行过的检查、结果和手动复现或验证步骤;相关平台尚未测试的,请明确注明。
4. 界面变化的截图或短录屏,以及兼容性和迁移方面的影响。
-请运行与改动相关的检查,在请求审查前处理相关 CI 失败。修复问题时,在可行的情况下补充或更新回归测试;纯文档修改可以通过检查格式和链接验证。构建方法见[从源码构建](guide/building.zh-CN.md)。
+请运行与改动相关的检查,在请求审查前处理本次改动引入的 CI 失败。如果已有 CI 故障或环境问题阻碍验证,请说明情况,共同排查。不要求贡献者自备全部平台的设备:请提供能够完成的验证和未覆盖范围,其他平台由 CI 或维护者协助验证。修复问题时,在可行的情况下补充或更新回归测试;纯文档修改可以通过检查格式和链接验证。构建方法见[从源码构建](guide/building.zh-CN.md)。
审查期间的后续提交应围绕原定目标。新想法请另开 Issue 或 PR。如果被要求拆分,请在拆分后的 PR 中链接原来的讨论。
+
+## 保留贡献来源
+
+维护者部分采纳 PR 或重新整理外部贡献时,会关联原 PR 和最终提交,说明哪些内容已采用、哪些尚未纳入。
+
+保留贡献者提交时,应保留原作者信息。将实质性的外部代码整理进新提交时,应记录相应贡献,例如使用贡献者提供的作者信息添加 `Co-authored-by` 署名。参考方案后重新实现的部分,应注明原提案并致谢,避免让人误以为原提交已被合并。
+
+对于这些规范发布或修订前已提交的 PR,应与贡献者沟通范围和拆分方式,不以事后新增的要求认定此前贡献不合规范。