Mermaid

外观

使用 Mermaid Chart 中的视觉编辑器设计和构建图表

Mermaid 贡献指南 ​

您决定参与开发？欢迎！

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

初始设置 ​

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

获取源代码 ​

在 GitHub 中，当您要进行更改并提交拉取请求时，首先要为 mermaid 存储库创建一个分支。

然后，您将克隆一个副本到您的本地开发机器（例如您编写代码的地方），以创建一个包含所有文件的副本供您使用。

提示

这里有一个 GitHub 文档，概述了该过程.

bash
git clone [email protected]/your-fork/mermaid

将存储库克隆到您的开发机器后，进入 mermaid 项目文件夹（mermaid 项目存储库的顶层目录）

bash
cd mermaid

安装要求 ​

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

主机

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

以下命令足以开始使用

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

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

Docker

安装 Docker。这几乎就是您所需要的。

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

bash
echo $DISPLAY

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

安装软件包 ​

主机

安装软件包

bash
pnpm install

Docker

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

确保 ./run 脚本可执行

bash
chmod +x run

提示

要获取详细的帮助，只需键入 ./run 或 ./run help。

它还嵌入了简短的开发快速入门指南。

然后安装软件包

bash
./run pnpm install

验证一切正常 ​

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

您可以运行 test 脚本以验证 pnpm 是否正常以及存储库是否已正确克隆

主机

bash
pnpm test

Docker

bash
./run pnpm test

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

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

信息

您可能会看到lint 或格式化警告。在这一步中，这些是正常的。

工作流程 ​

贡献过程非常简单直接

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

开发是在 develop 分支中进行的。

为了准备新版本的发布，维护人员从 develop 分支创建一个 release/vX.X.X 分支进行测试。发布后，我们将向 release 分支添加一个标签，并将它合并到 master 中。实时产品和在线文档是 master 分支中的内容。

签出新分支 ​

提示

所有新工作都应该基于 develop 分支。

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

签出 develop 分支，然后 fetch 或 pull 以更新它

bash
git checkout develop
git fetch # or `git pull`

为您的工作创建一个新分支

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

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

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

您始终可以检查当前的标签和分支前缀配置

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

如果您的工作特定于单个图表类型，最好将图表类型放在描述的开头。这将有助于我们按图表类型组织发行说明。

信息

在问题 2945 中描述的新功能，它向状态图添加了一种名为 'florbs' 的新箭头类型

feature/2945_state-diagram-new-arrow-florbs

提示

在问题 1123 中描述的一个错误，它会导致在多种图表类型中出现随机的难看的红色文本

bug/1123_fix_random_ugly_red_text

贡献代码 ​

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

代码在哪里？ ​

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

在本地运行 Mermaid ​

主机

bash
pnpm run dev

Docker

bash
./run dev

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

现在您已准备好进行更改！

进行更改 ​

查看https://127.0.0.1:9000。有一个演示列表，可用于查看和测试您的更改。

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

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

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

编写测试 ​

测试确保每个函数、模块或代码部分都按预期执行。当对代码进行其他更改时，这至关重要，以确保现有代码没有损坏（没有回归）。

同样重要的是，测试充当规范：它们指定代码执行的操作（或应该执行的操作）。无论何时有人对代码部分不熟悉，他们都应该能够阅读测试以全面了解它是做什么的以及为什么。

如果您要修复错误，您应该添加测试以确保您的代码已实际修复错误，以指定/描述代码正在执行的操作，并确保错误不再发生。（如果对这种情况进行了测试，错误根本就不会发生。）如果测试不准确，您可能需要更改现有测试。

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

单元测试 ​

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

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

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

主机

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

sh
pnpm test

编写新测试时，最好让测试在您进行更改时自动运行。您可以通过运行以下命令来实现。

sh
pnpm test:watch

Docker

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

sh
./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 中运行时，它将对渲染的图表进行快照，并将其与上次构建的快照进行比较，如果存在差异，则将其标记为待审核。

以下是渲染测试的外观

js
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 }
  );
});

更新文档 ​

提示

我们的文档在 packages/mermaid/src/docs 中管理。有关如何编辑的详细信息请参见 文档部分

如果用户无法知道事情已经改变，那么您实际上并没有为用户修复任何问题；您只是让 Mermaid 感觉像是坏掉了。同样，如果用户不知道您已经实现的新功能，它将永远保持未知和未使用。

必须更新文档，让用户知道内容已经更改和添加！如果您正在添加新功能，请在标题或描述中添加 (v<MERMAID_RELEASE_VERSION>+)。当发布发生时，它将自动替换为当前版本号。

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

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

创建另一个专门针对文档的问题。您需要帮助进行 PR，但如果您感到卡住了，请务必寻求帮助。当您觉得难以写出内容时，向某人解释并让他们向您提出澄清问题，这通常可以完成 80% 的工作！

如有疑问，请写下并提交您能写的内容。它可以在以后进行澄清和完善。（对于文档来说，有总比没有好！）

贡献文档 ​

如果文档中没有，就好像它从未发生过。那不会很悲伤吗？付出所有努力来实现这个功能？

文档在哪里？ ​

警告

不要更改 /docs 中的文件

docs 文件夹将在提交到 packages/mermaid/src/docs 时自动生成，并且 **不应** 手动编辑。

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

内容 mermaid.js.org 基于 master 分支的文档。提交到 master 分支的更新将在发布后反映在 Mermaid 文档 中。

在本地运行文档网站 ​

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

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

主机

bash
pnpm --filter mermaid run docs:dev

或

bash
cd packages/mermaid
pnpm docs:dev

Docker

bash
./run docs:dev

在浏览器中打开 https://127.0.0.1:3333/。

格式 ​

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

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

危险

不要使用 vitepress 特定的 markdown 语法 ::: warning，因为它不会被正确处理。

以下是一些示例

markdown
```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 构建。

警告

为了允许自动编译文档页面，您必须先在您的分支上启用 Github Actions

提交您的拉取请求 ​

信息

不要忘记推送您的更改

bash
git push -u origin docs/2910_update-guidelines

我们通过拉取请求 (PR) 进行所有更改。打开一个新的拉取请求。

目前，我们没有遵循任何关于拉取请求命名的严格规则。请给它一个有代表性的标题和简短的描述。还有一个 拉取请求模板 可以帮助您完成此操作。

如果描述中包含 神奇注释，您的 PR 将自动附加到该问题

markdown
Resolves #<your issue ID here>

恭喜您 ​

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

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

感谢您的帮助！