Merge pull request #2260 from deepseek-harness/codex/add-contributing-guide

docs: add contribution guide
2026-08-11 19:04:42 +08:00
parent eb83e0c615 8a6c3736e4
commit 35b4214e4e
12 changed files with 76 additions and 10 deletions
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write CONTRIBUTING.md
+CONTRIBUTING.md: 9dd90e8e032eb80384047e18d02e07cec6138ee2
+CONTRIBUTING.zh.md: 7d4e8849ab01af8407ccc6e85135dbb37ee2fc32
@@ -0,0 +1,23 @@
+# Contributing
+
+English | [中文](CONTRIBUTING.zh.md)
+
+Thank you for your interest in contributing to DeepSeek Harness!
+
+We deeply believe in the power of open source communities, and that belief has shaped this project from the very beginning.
+
+DeepSeek Harness is still at an early stage and under active development. We are sorry that we cannot accept external pull requests at the moment. However, contributing code to this repository is far from the only way to help. There are many other ways to get involved:
+
+- Identify and report issues or bugs in GitHub Discussions.
+  - Upvote discussions that you would like to bring to the team's attention. We are a very small team and may not be able to reply to every post, but we monitor them and consider them when allocating resources.
+- Contribute to the ecosystem:
+  - Create a plugin that excites you and share it with others.
+    - Associate your GitHub project with the `dsh-plugin` topic to help others discover your plugin.
+  - Write blog posts and how-to guides about DeepSeek Harness.
+  - Answer questions and help other members of the community.
+
+DeepSeek Harness is designed to be deeply customizable. We do not believe that packages in the official repository are inherently more important than packages created by the community. You may consider this repository an idea, an official showcase, and a source of inspiration, but not a mandate from us.
+
+We have already seen exciting projects emerge from the community, and we hope to see the ecosystem continue to grow in its own directions.
+
+Into the unknown.
@@ -0,0 +1,23 @@
+# 贡献
+
+[English](CONTRIBUTING.md) | 中文
+
+感谢你有兴趣为 DeepSeek Harness 作出贡献！
+
+我们深信开源社区的力量，这份信念从项目最初就塑造着 DeepSeek Harness。
+
+DeepSeek Harness 仍处于早期阶段，并在积极开发中。很抱歉，我们目前无法接受外部 PR（Pull Request）。但贡献代码远不是帮助这个仓库的唯一方式。你还可以通过许多其他方式参与其中：
+
+- 在 GitHub Discussions 中发现并报告问题或 bug。
+  - 为你希望引起团队关注的讨论投票。我们的团队规模很小，可能无法回复每个帖子，但我们会持续关注，并在分配资源时将这些讨论纳入考虑。
+- 为生态系统作出贡献：
+  - 创建令你感兴趣的插件，并分享给其他人。
+    - 为你的 GitHub 项目添加 `dsh-plugin` topic，帮助其他人发现你的插件。
+  - 撰写有关 DeepSeek Harness 的博客文章和操作指南。
+  - 回答问题并帮助其他社区成员。
+
+DeepSeek Harness 的设计支持深度定制。我们不认为官方仓库中的包在本质上比社区创建的包更重要。你可以将这个仓库视为一种思路、一个官方展示和一项灵感来源，而不是我们要求社区遵循的方向。
+
+我们已经看到社区中涌现出令人期待的项目，也希望生态系统继续沿着自己的方向发展。
+
+向未知进发。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
-README.md: b2d84672275a4ca996b6ea596c104abfaa52432a
-README.zh.md: 747a3c88bc129ad5dd24f5fa150a1661c4db0b11
+README.md: 9c19dfec19cba6f1364e4f9d5734af49675d68c2
+README.zh.md: 31d83ede854e9f0dfbbba1f8ce1094d043f6d829
@@ -88,3 +88,7 @@ DeepSeek Harness is currently in internal testing.
 [BSD 3-Clause](LICENSE)

 Third-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before contributing to this repository.
@@ -92,3 +92,7 @@ DeepSeek Harness 目前处于内测阶段。
 [BSD 3-Clause](LICENSE)

 第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。
+
+## 参与贡献
+
+向本仓库贡献前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/i18n/README.md
-README.md: 9875eb0c9924daa0b519923e9aac8a67de8cda61
-README.zh.md: eed73226dffd9bc1f6af7b21af5b0b77363878e2
+README.md: 23400801426f77dae5136406cd747dbe4b06a4c5
+README.zh.md: fe3cc7b5a5403fc9cf0c9ce536178d4fa7581e3c
@@ -41,7 +41,7 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co

 ## Scope and exclusions

-**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.
+**Scope**: the root CONTRIBUTING document, every non-vendor README, and every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.

 Generated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth, and freshness and pairing gates enforce their respective invariants independently; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source. A generated page's Chinese counterpart may rewrite only self-referential generation and maintenance statements that would otherwise be false for the reviewed translation; all technical content remains subject to the ordinary faithfulness rules.

@@ -41,7 +41,7 @@

 ## 范围与排除

-**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。
+**范围**：根目录 CONTRIBUTING 文档、除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。

 有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁与配对门禁各自独立强制其约束；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。生成页的中文对侧只能改写若直译便不再符合经评审译文事实的自指生成与维护说明；所有技术内容仍受普通忠实性规则约束。

@@ -182,6 +182,9 @@ describe('translation pairing records', () => {
 describe('translation scope discovery', () => {
  it.each([
    'README.md',
+    'CONTRIBUTING.md',
+    'CONTRIBUTING.zh.md',
+    'CONTRIBUTING.i18n.yaml',
    'apps/cli/README.md',
    'future/subtree/readme.md',
    'packages/example/README.zh.md',
@@ -195,6 +198,7 @@ describe('translation scope discovery', () => {

  it.each([
    'packages/example/guide.md',
+    'packages/example/CONTRIBUTING.md',
    'examples/tutorial.md',
    'website/reference.md',
    'packages/example/README.txt',
@@ -125,6 +125,7 @@ export interface TranslationPairingManifest {
 }

 const README_ARTIFACT = /(?:^|\/)readme(?:\.md|\.zh\.md|\.i18n\.yaml)$/i
+const ROOT_CONTRIBUTING_ARTIFACT = /^contributing(?:\.md|\.zh\.md|\.i18n\.yaml)$/i
 const NON_SOURCE_DIRECTORIES = new Set([
  'node_modules',
  'lib',
@@ -179,6 +180,7 @@ function isTranslationSourceExcluded(file: string): boolean {
 export function isTranslationScopeFile(file: string): boolean {
  return !file.startsWith('.agents/notes/archived/')
    && !isTranslationSourceExcluded(file) && (README_ARTIFACT.test(file)
+    || ROOT_CONTRIBUTING_ARTIFACT.test(file)
    || file.startsWith('.agents/notes/')
    || file.startsWith('docs/')
    || file.startsWith('python/'))