-
Notifications
You must be signed in to change notification settings - Fork 5
Contribution Guide
贡献路径取决于你改的是哪一层。先判断层级，再选入口。
| 你要改什么 | 首选位置 | 什么时候不该走这条路 |
|---|---|---|
| 补一条资源、补标签、补技术栈 | catalog/**/curated.json |
你要修的是全局规则或同步机制 |
| 修同步、去重、评分、发布逻辑 |
scripts/、.github/workflows/
|
你只是在修单条数据 |
| 改安装命令或平台适配 |
platforms/、install.sh、install.ps1
|
问题其实来自目录数据本身 |
| 补维护文档 | docs/wiki/ |
内容只是一次性研究或正式规格 |
| 做结构性变更 | 单独设计稿 / proposal / tasks | 只是局部字段修正或文案修正 |
如果这一步判断错了，后面的工作大概率都在补错误层的症状。
资源类贡献默认走 curated.json。这是当前仓库最稳定、最可控的人工入口。
典型场景包括：
- 上游还没收录这条资源
- 自动同步收到了，但标签和技术栈明显不够
- 描述不准确，影响搜索和推荐
- 安装信息缺失，导致资源虽然在目录里但几乎不可用
资源类贡献不适合用来解决这些问题：
- 分类逻辑本身有系统性偏差
- 去重策略误杀大量条目
- 某个同步脚本本来就抓错数据
- 平台命令的行为和目录层约定不一致
这些问题都不是单条数据能修好的。
至少保证这些字段是你自己确认过的：
nametypedescriptionsource_urlcategorytagsinstall
如果其中某个字段语义你说不清，就先不要提交。
资源类改动至少做这些检查：
- 跑
scripts/validate_curated.py - 检查
id是否重复 - 检查
source_url是否已经存在 - 检查描述是不是自然语言，不是关键词堆砌
curated.json 是人工纠偏入口，不是全局覆盖层。当前合并逻辑不会让 curated 无条件重写所有核心字段；它更适合补充，而不是接管事实来源。
改 scripts/、workflow、安装脚本之前，先回答三个问题：
- 改动影响哪一层。
- 会不会改变
catalog/index.json或发布产物。 - 你准备怎么验证不会引入新的系统性噪声。
这类改动可以解决机制问题，但也最容易把影响范围放大。
- 某个校验规则明显漏判或误判
- 某个 workflow 的命令、路径、触发条件明显错误
- 某段同步逻辑已知有确定性 bug
- 安装脚本和当前平台目录结构已经不匹配
- 你还没想清楚这是不是目录模型问题
- 你希望靠一个脚本同时补救上游质量差、历史数据脏和平台差异
- 你只能描述现象，无法定位层级
这时先回到 Architecture 和 Catalog Governance，不要直接下手。
文档也分层，不是都往一个地方写。
| 内容类型 | 放哪里 |
|---|---|
| 对外介绍、安装、使用 | README |
| 稳定维护说明、边界、操作入口 | docs/wiki/ |
| 深入研究、策略分析、专题设计 | 单独保存的研究文档 |
| proposal、design、tasks、spec | 单独维护的规格文档 |
最常见的问题不是“文档没写”，而是“写在了错误的位置”。位置错了，后面的人就会在 README 找维护手册，或在规格文档里找当前实现说明。
以下情况建议先把 proposal / design / tasks 写清楚，再做实现：
- 新增一类核心能力
- 调整目录模型或 schema 语义
- 改变去重、评分、治理原则
- 改变平台命令契约
- 引入新的长期维护流程
这些改动的共同点是：它们会改变多人协作的共同前提。没有 proposal 和 design，后面很难判断改动是偏离实现，还是偏离原意。
PR 至少说清：
- 你补了什么资源或字段
- 为什么现状不够
- 你怎么确认字段准确
PR 至少说清：
- 问题在哪一层
- 改动会影响哪些产物
- 你跑了什么验证
PR 至少说清：
- 为什么这段内容应该放在这里
- 它取代或补充了哪份现有说明
欢迎的改动有共性：
- 让目录更准
- 让安装更清楚
- 让维护动作更可解释
- 让自动化更稳定
不欢迎的改动也有共性：
- 靠兜底值掩盖不确定字段
- 用个例去污染全局规则
- 没有验证路径的大改
- 只因为“看起来更高级”就重构
通常没有意义。很多 index.json 是自动同步产物，下次同步会覆盖。
如果问题本质在目录数据，前端兼容只会把问题藏起来。
不是。curated 只表示这条记录进入了人工纠偏入口，不表示维护者承诺持续手工追踪它。
第一次参与时，最稳妥的路径仍然是：
- 修一条 curated 记录。
- 跑校验。
- 在 PR 里把问题和修改范围讲清楚。
- 不顺手改全局脚本。
先学会“改对层”，比第一次就改大系统更重要。