本文档提供了对 Mermaid 项目贡献的全面指南，涵盖了开发环境设置、工作流程、测试要求和代码提交程序。它侧重于向 Mermaid 图表生成库贡献代码、文档和测试的技术方面。
本指南涵盖了贡献过程本身。有关测试框架基础设施的信息，请参阅测试框架。有关 CI/CD 管道自动化的详细信息，请参阅CI/CD 管道。有关构建系统特定信息，请参阅构建与打包。
Mermaid 项目支持基于主机和基于 Docker 的开发环境。设置过程包括获取源代码、安装依赖项和配置开发工具。
开发环境要求
项目需要特定的工具和版本以确保一致的开发
| 环境 | 要求 | 安装命令 |
|---|---|---|
| 主机 | Node.js, pnpm | curl -fsSL https://get.pnpm.io/install.sh | sh - |
| 主机 | Node.js v20 | pnpm env use --global 20 |
| Docker | Docker, X11 服务器 | 特定平台的 Docker 安装 |
| Docker | 可执行运行脚本 | chmod +x run |
来源：CONTRIBUTING.md239-286 .gitignore1-55
Mermaid 遵循受 Git Flow 启发的分支策略，采用围绕 develop 分支的特定命名约定和开发实践。
分支命名约定
项目对所有分支使用结构化的命名约定
[type]/[issue-number]_[short-description]
| 组件 | 目的 | 示例 |
|---|---|---|
类型 | 更改类别 | feature, bug, chore, docs |
/ | 分组分隔符 | 必需的分隔符 |
issue-number | GitHub issue 引用 | 2910, 1123 |
_ | 描述分隔符 | 必需的下划线 |
short-description | 简要更改摘要 | state-diagram-new-arrow-florbs |
分支类型配置
分支前缀在 .github/pr-labeler.yml 中配置，并根据分支名称前缀自动为拉取请求分配标签。
来源：CONTRIBUTING.md168-188 CONTRIBUTING.md510-528
开发过程包括构建库、运行本地开发服务器以及使用提供的演示基础设施测试更改。
开发服务器特性
本地开发服务器提供热重载和演示文件服务
localhost:9000 服务演示文件和重建后的库packages/mermaid/src 的更改会触发自动重建demos/dev/example.html 以创建自定义测试图表localhost:9000/dev/your-file-name.html 提供服务来源：CONTRIBUTING.md244-286 CONTRIBUTING.md426-450
项目采用多种测试策略，包括单元测试、集成测试和视觉回归测试，以确保代码质量并防止回归。
按代码类型划分的测试要求
| 代码类别 | 测试要求 | 测试框架 |
|---|---|---|
| 核心逻辑 | 单元测试强制要求 | Vitest |
| 实用函数 | 单元测试强制要求 | Vitest |
| 解析器逻辑 | 单元测试强制要求 | Vitest |
| 渲染器 | 集成测试必需 | Cypress + imgSnapshotTest |
| 新功能 | 单元测试和集成测试 | Vitest + Cypress |
| Bug 修复 | 防止回归的测试 | 适当的框架 |
视觉回归测试使用带有 imgSnapshotTest 函数的标准化模式
文档在一个版本控制系统中维护，对源文件的更改会触发已发布文档站点的自动生成。
文档文件结构
文档系统对文件位置和编辑有严格的规定
packages/mermaid/src/docs/ 中进行docs/ 文件夹内容是自动生成的，绝不应手动编辑.vitepress/config.tsmaster 分支的内容发布到 mermaid.js.orgMarkdown 扩展
文档支持特殊格式块
| 块类型 | 语法 | 目的 |
|---|---|---|
| 注意 | ````markdownnote | 信息内容 |
| 提示 | ````markdowntip | 有用的建议 |
| 警告 | ````markdownwarning | 重要注意事项 |
| 危险 | ````markdowndanger | 严重警告 |
拉取请求过程包括代码提交、自动化测试和审查程序，以确保代码质量和项目一致性。
拉取请求（PR）要求
在提交拉取请求之前，请确保以下组件已完成
| 组件 | 要求 | 验证命令 |
|---|---|---|
| 代码更改 | 功能完善且经过测试 | pnpm test |
| 单元测试 | 为新代码编写 | pnpm test |
| 集成测试 | 为渲染更改添加 | pnpm cypress:open |
| 文档 | 为面向用户的更改更新 | pnpm docs:dev |
| 代码 Linting | 代码遵循样式指南 | pnpm lint |
| 分支名称 | 遵循命名约定 | 手动验证 |
自动化 PR 处理
系统提供多项自动化功能
Resolves #<issue-number> 以实现自动链接来源：CONTRIBUTING.md510-540 .github/workflows/link-checker.yml22-52
审查过程包括多个阶段
develop