Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
364 lines (244 loc) · 8.57 KB

CONTRIBUTING.md

File metadata and controls

364 lines (244 loc) · 8.57 KB
Raw

贡献指南

感谢您对 GameDevMind 项目的关注！我们欢迎所有形式的贡献。

📋 目录

📜 行为准则

请保持友好和尊重，我们致力于为每个人提供开放和欢迎的环境。

🤝 如何贡献

报告问题

如果您发现了问题或有改进建议，请：

  1. 检查 Issues 中是否已有相关问题
  2. 如果没有，请创建新的 Issue，并：
    • 使用清晰的标题
    • 详细描述问题或建议
    • 如果可能，提供复现步骤或示例

贡献内容

  1. Fork 本仓库
  2. 创建 您的特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交 您的更改 (git commit -m 'Add some AmazingFeature')
  4. 推送 到分支 (git push origin feature/AmazingFeature)
  5. 开启 一个 Pull Request

📝 文档编写规范

文件命名

详见 docs/文档命名规范.md。摘要：

  • 使用中文命名，格式：编号.标题.md
  • 例如：1.1.1.编程语言基础概念.md
  • 编号格式：主分类.子分类.具体主题.md

Markdown 格式

本仓库允许在 Markdown 中混用少量 HTML，以保持 GitHub 上的阅读样式与历史文档一致。

标题与简介

  • 推荐：## 标题（二级标题作为文档主标题）
  • 允许：<p>...</p> 包裹导语段落
  • 允许：<br/> 与 **关键词:** / **标签:** 组合（见模板）

❌ 避免：无意义的嵌套 <div>、内联脚本、过时样式

✅ 推荐结构（见 template/z.模板.md）：

## 标题
<p>简介</p>

**关键词:**<br/>
*关键词1, 关键词2*

**标签:**<br/>
*等级: 中级, 阶段: 开发, 分类: 技术能力, 角色: 客户端开发*

允许的 HTML 标签

p, br, table, tr, td, th, a, img, h1–h6（含 align 等展示属性）、strong, em

只读类文档（如 README）可使用更丰富的 HTML；mds/ 叶子文档以保持简洁表格 + 上述标签为主。

标题（旧规范已废止）

不使用 HTML 标签 → 已改为「允许有限 HTML」，与现有 100+ 篇文档一致。

图片

  • 使用相对路径，不要加 ?raw=true
  • 格式：![图片描述](../../exports/图片名.png)
  • 确保图片存在于 exports/ 或 images/ 目录

链接

  • 内部链接使用相对路径
  • 外部链接使用完整 URL
  • 格式：[链接文本](路径或URL)

代码块

  • 指定语言类型
  • 格式： 
    ```语言
代码内容

列表

  • 有序列表使用数字：1. 项目
  • 无序列表使用 - 或 *：- 项目

文档结构

每个叶子文档应包含以下部分（完整模板见 template/z.模板.md）：

## 标题

<p>
简介或说明
</p>

**关键词:**<br/>
*关键词1, 关键词2, AI Coding*

**标签:**<br/>
*等级: 中级, 阶段: 开发, 分类: 技术能力, 角色: 客户端开发*

## 目录
（可选）

## 小节标题
（表格：是什么 / 问题 / 要点）

## 更多资料
（可选）

内容要求

  1. 准确性：确保内容准确、最新
  2. 完整性：提供足够的信息，但保持简洁
  3. 可读性：使用清晰的语言，适当使用列表和表格
  4. 链接：提供相关资源的链接

实战案例格式 (cases/)

案例需有完整排查过程，让读者有"亲身经历"感。参考 cases/README.md 模板。

# 案例标题

## 背景
- 游戏类型、技术栈、团队规模

## 症状
- 具体表现、影响范围

## 排查过程
- 每一步的假设与验证

## 根因分析
- 根本原因及触发条件

## 解决方案
- 改了哪些、为什么这样改

## 效果
- 改前 vs 改后数据对比

## 经验教训
- 如何避免、检查清单

## 图谱知识点映射
- [对应文档](../mds/...)

规范：

  • 标题不添加 emoji 前缀
  • 章节名不含步骤数（如 ## 排查过程，而非 ## 排查过程（5步））
  • 内部链接使用相对路径

AI 对话案例格式 (ai-cases/)

展示真实 AI 协作过程。参考 ai-cases/README.md 模板。

# 对话标题

## 背景
- 项目场景与目标

## 对话记录
### 第一轮
> 我的 prompt...

AI 回复摘要...

### 第二轮
> 我的追问...

AI 修正摘要...

## 最终成果
- 完整代码或方案

## 关键收获
- 与 AI 协作的经验总结

## 图谱知识点映射
- [对应文档](../mds/...)

规范：

  • Prompt 必须用 > 块引用包裹
  • AI 回复需附摘要
  • 标题不添加 emoji 前缀

📤 提交规范

Commit Message 格式

使用以下格式：

<type>(<scope>): <subject>

<body>

<footer>

Type 类型

  • feat: 新功能
  • fix: 修复问题
  • docs: 文档更新
  • style: 格式调整（不影响代码）
  • refactor: 重构
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建过程或辅助工具的变动

示例

docs(基础能力): 更新编程语言章节

添加了 Rust 语言相关内容
更新了 C++ 版本说明

Closes #123

提交频率

  • 每个逻辑更改提交一次
  • 保持提交信息清晰
  • 避免提交过多小改动

🔄 Pull Request 流程

创建 PR 前

  1. ✅ 确保代码/文档符合规范
  2. ✅ 确保所有链接有效
  3. ✅ 确保图片路径正确
  4. ✅ 更新相关文档（如需要）
  5. ✅ 测试您的更改

PR 标题格式

<type>: <简短描述>

示例：

  • docs: 添加设计模式章节
  • fix: 修复图片链接错误
  • feat: 添加新工具脚本

PR 描述

请包含：

  1. 变更说明：简要描述您的更改
  2. 相关 Issue：如果有，链接相关 Issue
  3. 检查清单：
    • 文档格式符合规范
    • 所有链接有效
    • 图片路径正确
    • 已更新相关文档

审查流程

  1. 提交 PR 后，维护者会进行审查
  2. 可能需要修改，请根据反馈进行调整
  3. 审查通过后，PR 会被合并

🛠️ 开发环境设置

必需工具

  • Git
  • Markdown 编辑器（推荐 VS Code）
  • （可选）Node.js（用于运行工具脚本）

本地测试

  1. Fork 并克隆仓库
  2. 安装检查依赖：pip install -r tools/check/requirements.txt
  3. 运行文档检查： 
    python tools/check/check_docs.py
python tools/check/check_images.py
  4. 预览更改效果

详见 tools/check/README.md。

📚 资源

❓ 问题

如果您有任何问题，请：

  1. 查看 Issues
  2. 在 Discussions 中提问
  3. 加入 QQ 群：242500383

🙏 致谢

感谢所有贡献者的支持！您的贡献让这个项目变得更好。

🏆 贡献者激励体系

为鼓励持续贡献，我们建立三级贡献者成长路径：

等级 条件 权益
🥉 内容贡献者 1个以上 PR 被合并（文档/代码/案例/AI对话 任一类） README 贡献者名单署名 + GitHub 个人链接
🥈 核心贡献者 5个以上 PR 被合并，或持续活跃贡献 3 个月以上 以上全部 + 仓库 Collaborator 权限 + 专属 Issue 指派
🥇 维护者 长期深度参与项目方向讨论，经现有维护者共识邀请 以上全部 + 仓库 Admin 权限 + 项目决策参与

贡献类型与计分（非严格，作为活跃度参考）：

贡献类型 说明 参考权重
🧠 知识文档 新增/完善知识图谱文档 ⭐⭐⭐⭐⭐
🏥 实战案例 提交真实排查案例 ⭐⭐⭐⭐⭐
💻 代码示例 新增配套代码示例 ⭐⭐⭐⭐
🤖 AI对话 提交 AI 协作案例 ⭐⭐⭐
🐛 问题修复 修复文档错误、死链、格式 ⭐⭐
💡 建议/讨论 提出有价值的 Issue/Discussion ⭐

💬 奖励池（待社区壮大后启动）： 贡献突出者有机会获得技术书籍、在线课程、顶游社技术咨询服务折扣等。

特别贡献： 如果您贡献了整篇新知识文档（≥200行），我们会特别鸣谢并在文档作者字段署名。