Skip to content

Latest commit

 

History

History
59 lines (39 loc) · 3.71 KB

CONTRIBUTING.md

File metadata and controls

59 lines (39 loc) · 3.71 KB

贡献指南 · moxsh-plugins

.mox 插件目录(catalog)、清单规范与官方插件仓库。主仓库在 GitHub;Gitee 镜像只读,请不要在镜像上提 Issue / PR。

规则按 【必须】 和 【建议】 分级。必须 只有下面 5 条,其余都是建议——我们不打算用流程劝退贡献者。

【必须】遵守的 5 条

  1. 【必须】 安全漏洞不要写进公开 Issue / PR,改走 SECURITY.md 的私密渠道。
  2. 【必须】 PR 描述写清三件事:改了什么 / 为什么改 / 怎么验证。缺任一项会被要求补充。
  3. 【必须】 跑过下方「本地验证」中与你改动对应的那条命令,并在 PR 里贴结果;跑不了要写明原因(缺设备、缺密钥、环境限制都算正当理由)。
  4. 【必须】 不提交密钥、token、keystore、账号数据、真实用户日志。CI 有密钥扫描会拦。
  5. 【必须】 遵守 行为准则。

【建议】但绝不强制

  • Commit message 用 Conventional Commits(feat: / fix: / docs: / ci: / refactor:);写得清楚就行,格式不强制。
  • 从 main 开功能分支,分支名随意。
  • 大改动(新依赖、改公开 API、改目录结构、动 CI/发布)先开 Issue 聊两句,避免白做。
  • 草稿 PR 随时可开,做一半也能发,方便早一点收到反馈。
  • 一个 PR 只解决一件事;顺手修的无关改动放在另一个 PR 更好。

明确不要求的东西

以下都不需要,别因为没做这些而不敢提 PR:GPG 签名提交、DCO / CLA 签署、强制 rebase、压缩成单个 commit、英文提交信息、强制关联 Issue 编号、特定 IDE 或格式化工具。

报告问题

提 Issue 前先搜一下有没有同类问题。建议提供:复现步骤、期望行为 vs 实际行为、环境(系统/浏览器/设备/版本)、相关日志(贴之前先删掉密钥和个人信息)。用 .github/ISSUE_TEMPLATE 里的表单会自动带上这些字段。

复现不了也可以提,说明「偶现」即可;但不要把猜测当结论写进标题。

本地验证

改动范围 命令 / 说明
catalog / plugins 校验(CI 同款,推荐) node scripts/check-schemas.mjs:校验 schema 规则有效性 + catalog.json / plugins.json 索引一致性
catalog 基础语法 python3 -m json.tool catalog.json >/dev/null && python3 -m json.tool schema/catalog.schema.json >/dev/null
条目与 schema 对齐 新增条目后确认字段满足 schema/catalog.schema.json 与 schema/entry-schema.json

命令以仓库当前内容为准;如果和你本地不一致,以 CI 工作流 里实际跑的为准,并欢迎顺手修这份文档。

代码约定

  • 遵循同目录现有风格,别为了「统一」大范围重排别人的代码。
  • 新增第三方依赖请在 PR 里说明理由(体积、许可证、维护状态)。
  • 涉及安全边界的改动(鉴权、签名、下载校验、权限模型)请在 PR 里显式说明「为什么这样不会削弱防护」。
  • 注释写「为什么」,不写「这行在干嘛」。

审核与合并

  • 审核责任见 CODEOWNERS。
  • 维护者通常在 3 天内回应;超时直接 @ 一下即可,不用客气。
  • 小问题(错别字、格式、补个测试)维护者可能直接帮你补上再合并,会告知你。
  • CI 红不等于你的改动有问题:本仓 CI 不依赖签名密钥;若 job 因环境/网络抖动失败,直接在 PR 里说明即可重跑。

许可

本仓采用 MIT。提交贡献即表示同意你的代码按该许可发布;贡献者保留署名权。