Mermaid 贡献指南 ​

你决定参与开发吗？欢迎！

我们正在努力使我们的指南尽可能明确和详细。

初始设置 ​

初始设置包括3个主要步骤：

获取源代码 ​

在GitHub中，当你打算进行更改并提交拉取请求时，首先需要fork一个mermaid仓库。

然后你将一个副本克隆到你的本地开发机器上（例如你编写代码的地方），以获取所有文件的副本进行工作。

git clone git@github.com/your-fork/mermaid

一旦你将仓库克隆到你的开发机器上，切换到mermaid项目文件夹（mermaid项目仓库的顶级目录）

cd mermaid

安装要求 ​

我们支持在Docker环境中进行开发，同时也支持主机设置。您可以根据自己的偏好进行选择。

主机

这些是我们用于处理代码和文档的工具：

• Node.js.
• pnpm 包管理器。

以下命令应该足以开始：

curl -fsSL https://get.pnpm.io/install.sh | sh -
pnpm env use --global 20

您可能还需要重新加载 .shrc 或 .bashrc 文件。

Docker

Install Docker。这几乎就是你所需要的全部。

可选地，要在Docker内运行GUI（Cypress），您还需要安装X11服务器。您可能已经安装了它，因此可以通过运行以下命令来检查：

echo $DISPLAY

如果$DISPLAY变量不为空，则表示X11服务器正在运行。否则，您可能需要安装一个。

安装包 ​

主机

安装包：

pnpm install

Docker

对于使用Docker进行开发，有一个自文档化的run bash脚本，它为docker compose命令提供了方便的别名。

确保 ./run 脚本是可执行的：

chmod +x run

然后安装包：

./run pnpm install

验证一切正常 ​

此步骤是可选的，但它有助于确保在您开始进行任何更改之前，开发分支中的所有内容都是正常的。

你可以运行test脚本来验证pnpm是否正常工作并且仓库是否已正确克隆：

主机

pnpm test

Docker

./run pnpm test

test 脚本和其他脚本位于顶层的 package.json 文件中。

所有测试都应成功运行，没有任何错误或失败。

工作流程 ​

贡献过程非常简单直接：

Mermaid 使用了一种受 Git Flow 启发的分支方法。

开发在develop分支中进行。

为了准备一个新版本的发布，维护者会从develop分支创建一个release/vX.X.X分支进行测试。一旦发布完成，我们会给release分支添加一个标签，并将其与master分支合并。实际产品和在线文档的内容就是master分支中的内容。

创建一个新分支 ​

确保你有最新版本的develop分支。

查看develop分支，然后fetch或pull以更新它：

git checkout develop
git fetch # or `git pull`

为你的工作创建一个新分支：

git checkout -b docs/2910_update-contributing-guidelines

我们使用以下命名约定来命名分支：

[feature | bug | chore | docs]/[issue number]_[short-description]

您可以随时查看当前的标签和分支前缀配置

• 第一部分是变更的类型：feature、bug、chore、docs
• 后面跟着一个斜杠 (/)，这有助于在许多git工具中将相似类型分组在一起
• 接着是问题编号，例如2910
• 后面跟着一个下划线 (_)
• 接着是一个简短描述，使用破折号（-）或下划线（_）代替空格

如果你的工作针对特定的图表类型，最好在描述的开头注明图表类型。这将帮助我们按图表类型组织发布说明。

贡献代码 ​

代码是每个软件项目的核心。我们努力使其变得更好。如果不是我们，那会是谁呢？

代码位于何处？ ​

Mermaid 的核心位于 packages/mermaid/src 下。

本地运行 Mermaid ​

主机

pnpm run dev

Docker

./run dev

启动开发服务器后，在浏览器中打开 http://localhost:9000。

现在你已经准备好进行更改了！

进行更改 ​

请查看http://localhost:9000。这里有一系列演示，可以用来查看和测试您的更改。

如果你需要一个特定的图表，你可以在/demos/dev中复制example.html文件，并在你的副本中添加你自己的mermaid代码。

这将在http://localhost:9000/dev/your-file-name.html上提供服务。在代码更改后，开发服务器将重新构建mermaid库并自动重新加载页面。

根据需要编辑packages/mermaid/src中的文件。

编写测试 ​

测试确保每个函数、模块或代码部分按照其声明的方式工作。这在其他更改时尤为重要，以确保现有代码不会被破坏（没有回归）。

同样重要的是，测试充当规范：它们指定了代码的功能（或应该做什么）。每当有人对某段代码不熟悉时，他们应该能够通过阅读测试来全面了解它的功能及其原因。

如果你正在修复一个错误，你应该添加测试以确保你的代码实际上已经修复了这个错误，以指定/描述代码正在做什么，并确保这个错误不会再次发生。（如果之前有针对这种情况的测试，这个错误一开始就不会发生。）如果现有的测试不准确，你可能需要更改它们。

如果您正在添加功能，您肯定需要添加测试。根据您的功能的大小，您可能需要添加集成测试。

单元测试 ​

单元测试是测试单个函数或模块的测试。它们最容易编写且运行速度最快。

除了渲染器之外，所有代码都必须进行单元测试。（渲染器通过集成测试进行测试。）

我们使用 Vitest 来运行单元测试。

主机

您可以使用以下命令来运行单元测试：

pnpm test

在编写新测试时，随着您进行更改，让测试自动运行会更容易。您可以通过运行以下命令来实现这一点：

pnpm test:watch

Docker

使用 Docker 时，请在命令前加上 ./run：

./run pnpm test

集成 / 端到端 (E2E) 测试 ​

这些测试图表的渲染和视觉外观。

这确保了在E2E中该功能的渲染将在未来的发布过程中得到审查。减少它崩溃的机会！

开始使用E2E测试：

主机

• 运行 pnpm dev 以启动开发服务器
• 通过运行 pnpm cypress:open 启动 Cypress

Docker

• 启用x11服务器的本地连接 xhost +local:
• 运行 ./run pnpm dev 以启动开发服务器
• 通过运行 ./run pnpm cypress:open --project . 启动 Cypress

渲染测试的创建非常直接。有一个函数 imgSnapshotTest，它接受文本形式的图表和mermaid选项，并在Cypress中渲染该图表。

在CI中运行时，它将拍摄渲染图的快照，并将其与上次构建的快照进行比较，如果不同则标记为需要审查。

这是一个渲染测试的样子：

it('should render forks and joins', () => {
  imgSnapshotTest(
    `
    stateDiagram
    state fork_state <<fork>>
      [*] --> fork_state
      fork_state --> State2
      fork_state --> State3

      state join_state <<join>>
      State2 --> join_state
      State3 --> join_state
      join_state --> State4
      State4 --> [*]
    `,
    { logLevel: 0 }
  );
});

更新文档 ​

如果用户无法知道事情已经改变，那么你并没有真正为用户修复任何东西；你只是让Mermaid感觉更加破碎。同样，如果用户不知道你实现了一个新功能，它将永远被忽视和未使用。

文档需要更新，以便用户知道已经进行了更改和添加！如果您正在添加新功能，请在标题或描述中添加(v+)。在发布时，它将自动替换为当前版本号。

例如：# 功能名称 (v+)

我们知道，有时编写代码和编写用户文档可能会很困难。

为文档创建一个单独的问题。你需要帮助处理PR，但如果你感到困惑，一定要寻求帮助。当你觉得写东西很困难时，向某人解释并让那个人问你澄清问题通常可以完成80%的工作！

当有疑问时，写下并提交你能写的内容。稍后可以澄清和完善。（对于文档来说，有总比没有好！）

贡献文档 ​

如果它不在文档中，就像它从未发生过一样。那不是很可悲吗？考虑到为这个功能付出的所有努力？

文档位于何处？ ​

文档位于packages/mermaid/src/docs文件夹中。只需选择正确的部分并开始输入。

mermaid.js.org 的内容基于 master 分支的文档。提交到 master 分支的更新一旦发布，就会反映在 Mermaid Docs 中。

本地运行文档网站 ​

Mermaid 文档站点 由 Vitepress 提供支持。

启动文档站点的开发服务器

主机

pnpm --filter mermaid run docs:dev

或

cd packages/mermaid
pnpm docs:dev

Docker

./run docs:dev

在浏览器中打开 http://localhost:3333/。

格式化 ​

文档是用Markdown编写的。要熟悉其语法，请参阅GitHub Markdown帮助页面。

你可以使用note、tip、warning和danger在三重反引号中添加注释、提示、警告或危险框。

以下是一些示例：

```note
This is a note
```

```tip
This is a tip
```

```warning
This is a warning
```

```danger
This is a danger alert
```

导航 ​

如果你想提议更改文档的组织方式，例如添加新部分或重新排列或重命名部分，你必须更新侧边栏导航，这是在vitepress配置中定义的。同样适用于顶部栏。

构建文档 ​

/docs 文件夹的内容是通过 Github Actions 构建的。

提交你的拉取请求 ​

git push -u origin docs/2910_update-guidelines

我们通过拉取请求（PRs）进行所有更改。打开一个新的。

目前我们没有遵循任何严格的规则来命名PR。给它一个有代表性的标题和简短的描述。还有一个pull request template可以帮助你完成这项工作。

如果描述中包含一个魔法注释，你的PR将自动附加到该问题：

Resolves #<your issue ID here>

恭喜 ​

您已成功提交改进！接下来是什么？

• PRs将由活跃的维护者进行审查，他们将根据需要提供反馈并请求更改。
• 维护者将在必要时请求knsv的审查。
• 一旦PR被批准，维护者将把PR合并到develop分支。
• 当发布准备就绪时，将创建release/x.x.x分支，进行广泛测试，knsv将负责发布过程。

感谢您的帮助！