🤝 CONTRIBUTING.md

# 贡献指南 感谢你对 [项目名] 的关注！我们欢迎所有形式的贡献， 包括但不限于：Bug 报告、功能建议、文档改进、代码贡献。 ## 🚀 5 分钟快速贡献 ### 修 Typo / 文档改进（最简单） 1. Fork 本仓库 2. 在 GitHub 网页上直接编辑文件 3. 提交 Pull Request 4. ✅ 完成！不需要本地安装任何东西 ### 代码贡献 \`\`\`bash # 1. Fork + Clone git clone https://github.com/YOUR_USERNAME/repo.git cd repo # 2. 安装依赖 npm install # 3. 创建分支 git checkout -b fix/my-fix # 4. 开发 + 测试 npm run dev npm test # 5. 提交（请遵循 Conventional Commits） git commit -m "fix: 修复了 XX 问题" # 6. 推送 + PR git push origin fix/my-fix # 在 GitHub 上创建 Pull Request \`\`\` ## 🎯 寻找适合你的 Issue - 🟢 `good first issue` — 新手友好，5-30 分钟 - 🟡 `help wanted` — 需要帮助，可能较复杂 - 🔴 `breaking change` — 需要核心维护者讨论 ## 📏 代码规范 我们使用自动化工具确保代码风格一致： - **ESLint** + **Prettier** 自动格式化 - `npm run lint` 检查代码风格 - `npm run format` 自动修复 - 提交前自动检查（Husky + lint-staged） ## ✅ PR 检查清单 - [ ] 通过所有测试 (`npm test`) - [ ] 代码风格检查通过 (`npm run lint`) - [ ] 新功能有对应测试 - [ ] 文档已更新（如适用） - [ ] 遵循 [Conventional Commits](https://www.conventionalcommits.org/) - [ ] 没有合并冲突 ## 🐛 Bug 报告模板 **描述**: 清晰描述 Bug 是什么 **复现步骤**: 1. ... 2. ... 3. ... **期望行为**: 应该发生什么 **实际行为**: 实际发生了什么 **环境**: OS / Node 版本 / 浏览器 ## 💬 需要帮助？ - GitHub Discussions: [链接] - Discord: [链接] - 邮件: [邮箱] ## 📄 License 提交贡献即表示你同意你的代码将在 [License] 下发布。

# .github/ISSUE_TEMPLATE/bug_report.yml name: 🐛 Bug 报告 description: 报告一个 Bug labels: ["bug", "triage"] body: - type: markdown attributes: value: | 感谢报告 Bug！请填写以下信息帮助我们快速定位问题。 - type: textarea id: description attributes: label: Bug 描述 description: 清晰描述你遇到的问题 placeholder: "当我执行 X 时，Y 发生了，但我期望 Z" validations: required: true - type: textarea id: steps attributes: label: 复现步骤 description: 详细步骤让别人也能复现 placeholder: | 1. 安装版本 X.X.X 2. 运行命令 Y 3. 输入 Z 4. 看到错误 validations: required: true - type: textarea id: expected attributes: label: 期望行为 validations: required: true - type: textarea id: actual attributes: label: 实际行为 validations: required: true - type: input id: version attributes: label: 版本号 placeholder: "e.g. v1.2.3" validations: required: true - type: dropdown id: os attributes: label: 操作系统 options: - macOS - Linux - Windows - Other validations: required: true - type: textarea id: logs attributes: label: 相关日志 description: 请粘贴相关错误日志 render: shell

# .github/workflows/pr-check.yml name: PR Check on: pull_request: types: [opened, synchronize, reopened] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 cache: 'npm' - run: npm ci # 代码风格检查 - name: Lint run: npm run lint # 类型检查 - name: Type Check run: npm run typecheck # 测试 - name: Test run: npm test -- --coverage # 构建检查 - name: Build run: npm run build # PR 大小检查（防止超大 PR） - name: PR Size Check uses: actions/github-script@v7 with: script: | const { data: files } = await github.rest.pulls.listFiles({ owner: context.repo.owner, repo: context.repo.repo, pull_number: context.payload.pull_request.number }); const totalChanges = files.reduce( (sum, f) => sum + f.changes, 0 ); if (totalChanges > 500) { await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.payload.pull_request.number, body: `⚠️ 这个 PR 有 ${totalChanges} 处变更，请考虑拆分为更小的 PR。` }); } # 自动标记 - name: Auto Label uses: actions/labeler@v5 with: repo-token: ${{ secrets.GITHUB_TOKEN }}

# 在项目根目录创建 CODE_OF_CONDUCT.md # 直接从 Contributor Covenant 官网复制最新版本 # https://www.contributor-covenant.org/ # 或在 GitHub 创建项目时勾选 "Add Code of Conduct"

# package.json — 提交前自动检查 { "lint-staged": { "*.{js,ts}": ["eslint --fix", "prettier --write"], "*.{md,json,yml}": ["prettier --write"] }, "husky": { "hooks": { "pre-commit": "lint-staged", "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } } } # commitlint.config.js — Conventional Commits 强制 module.exports = { extends: ['@commitlint/config-conventional'], rules: { 'type-enum': [2, 'always', [ 'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert' ]], 'subject-max-length': [2, 'always', 72] } };