Mermaid 贡献指南

🌐 Mermaid Contributing Guide

你决定参与开发？欢迎！

🌐 You decided to take part in the development? Welcome!

我们正在努力让我们的指导方针对你尽可能明确和详细。

🌐 We are trying to make our guidelines for you as explicit and detailed as possible.

初始设置

🌐 Initial Setup

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

🌐 Initial setup consists of 3 main steps:

获取源代码

🌐 Get the Source Code

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

🌐 In GitHub, you first fork a mermaid repository when you are going to make changes and submit pull requests.

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

🌐 Then you clone a copy to your local development machine (e.g. where you code) to make a copy with all the files to work with.

提示

这是一个 GitHub 文档，概述了该流程。

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

将代码库克隆到你的开发机器后，进入 mermaid 项目文件夹（mermaid 项目仓库的顶层目录）

🌐 Once you have cloned the repository onto your development machine, change into the mermaid project folder (the top level directory of the mermaid project repository)

cd mermaid

安装需求

🌐 Install Requirements

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

🌐 We support development within Docker environment along with host setup. You may choose it up to your preferences.

主机

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

🌐 These are the tools we use for working with the code and documentation:

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

以下命令应该足够用来开始：

🌐 The following commands must be sufficient enough to start with:

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

之后你可能还需要重新加载 .shrc 或 .bashrc。

🌐 You may also need to reload .shrc or .bashrc afterwards.

Docker

安装 Docker。这几乎就是你所需要做的全部了。

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

🌐 Optionally, to run GUI (Cypress) within Docker you will also need an X11 server installed. You might already have it installed, so check this by running:

echo $DISPLAY

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

🌐 If the $DISPLAY variable is not empty, then an X11 server is running. Otherwise you may need to install one.

安装软件包

🌐 Install Packages

主机

安装软件包：

🌐 Install packages:

pnpm install

Docker

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

🌐 For development using Docker there is a self-documented run bash script, which provides convenient aliases for docker compose commands.

确保 ./run 脚本可执行：

🌐 Make sure that ./run script is executable:

chmod +x run

提示

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

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

然后安装软件包：

🌐 Then install packages:

./run pnpm install

验证所有功能是否正常

🌐 Verify Everything Works

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

🌐 This step is optional, but it helps to make sure that everything in development branch was OK before you started making any changes.

你可以运行 test 脚本来验证 pnpm 是否正常工作，同时确认仓库是否已被正确克隆：

🌐 You can run the test script to verify that pnpm is working and that the repository has been cloned correctly:

主机

pnpm test

Docker

./run pnpm test

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

🌐 The test script and others are in the top-level package.json file.

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

🌐 All tests should run successfully without any errors or failures.

信息

你可能会看到 lint 或 formatting 警告。在这一步中这是正常的。

工作流程

🌐 Workflow

贡献流程非常简单明了：

🌐 Contributing process is very simple and straightforward:

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

🌐 Mermaid uses a Git Flow–inspired approach to branching.

开发在 develop 分支上进行。

🌐 Development is done in the develop branch.

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

🌐 To prepare a new version for release the maintainers create a release/vX.X.X branch from develop for testing. Once the release happens we add a tag to the release branch and merge it with master. The live product and on-line documentation are what is in the master branch.

检出一个新分支

🌐 Checkout a New Branch

提示

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

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

🌐 Make sure you have the most up-to-date version of the develop branch.

查看 develop 分支，然后使用 fetch 或 pull 来更新它：

🌐 Check out the develop branch, then fetch or pull to update it:

git checkout develop
git fetch # or `git pull`

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

🌐 Create a new branch for your work:

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

我们对分支使用以下命名规范：

🌐 We use the following naming convention for branches:

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

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

🌐 You can always check current configuration of labelling and branch prefixes

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

如果你的工作特定于某一种图表类型，最好在描述开头注明图表类型。这将有助于我们按图表类型整理发布说明。

🌐 If your work is specific to a single diagram type, it is a good idea to put the diagram type at the start of the description. This will help us keep release notes organized by a diagram type.

信息

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

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

提示

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

bug/1123_fix_random_ugly_red_text

贡献代码

🌐 Contributing Code

代码是每个软件项目的核心。我们努力让它变得更好。如果不是我们，还有谁呢？

🌐 Code is the heart of every software project. We strive to make it better. Who if not us?

代码位于何处？

🌐 Where is the Code Located?

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

🌐 The core of Mermaid is located under packages/mermaid/src.

本地构建 Mermaid

🌐 Building Mermaid Locally

主机

pnpm run build

Docker

./run build

这将构建 Mermaid 库和文档网站。

🌐 This will build the Mermaid library and the documentation site.

本地运行 Mermaid

🌐 Running Mermaid Locally

主机

pnpm run dev

Docker

./run dev

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

现在你可以开始进行修改了！

🌐 Now you are ready to make your changes!

做出更改

🌐 Make Changes

看看 http://localhost:9000。那里有一个演示列表，可以用来查看和测试你的更改。

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

🌐 If you need a specific diagram, you can duplicate the example.html file in /demos/dev and add your own mermaid code to your copy.

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

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

🌐 Edit files in packages/mermaid/src as required.

编写测试

🌐 Write Tests

测试确保每个函数、模块或代码部分都能按照预期工作。这在进行其他更改时尤为重要，以确保现有代码不会被破坏（无回归）。

🌐 Tests ensure that each function, module, or part of code does what it says it will do. This is critically important when other changes are made to ensure that existing code is not broken (no regression).

同样重要的是，测试也起着 规范说明 的作用：它们规定了代码的功能（或应有的功能）。每当有人接触某段新代码时，他们应该能够通过阅读测试来全面了解代码的具体功能及其原因。

🌐 Just as important, the tests act as specifications: they specify what the code does (or should do). Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why.

如果你正在修复一个漏洞，你应该添加测试来确保你的代码确实修复了该漏洞，说明/描述代码的功能，并确保该漏洞不再发生。 （如果之前有针对该情况的测试，这个漏洞根本就不会发生。） 如果现有的测试不准确，你可能需要修改它们。

🌐 If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. (If there had been a test for the situation, the bug never would have happened in the first place.) You may need to change existing tests if they were inaccurate.

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

🌐 If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests.

单元测试

🌐 Unit Tests

单元测试是针对单个函数或模块的测试。它们是最容易编写和运行最快的测试。

🌐 Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run.

单元测试对于除了布局测试之外的所有代码都是强制性的。（布局通过集成测试进行测试。）

🌐 Unit tests are mandatory for all code except the layout tests. (The layouts are tested with integration tests.)

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

🌐 We use Vitest to run unit tests.

主机

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

🌐 You can use the following command to run the unit tests:

pnpm test

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

🌐 When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command:

pnpm test:watch

Docker

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

🌐 When using Docker prepend your command with ./run:

./run pnpm test

测试 DOM

🌐 Testing the DOM

只要不涉及布局，就可以使用 jsdomIt 来测试 Mermaid 中与 DOM 交互的任何部分。

🌐 One can use jsdomIt to test any part of Mermaid that interacts with the DOM, as long as it is not related to the layout.

函数 jsdomIt（在 utils.ts 中开发）重写了来自 vitest 的 it，并创建了一个伪浏览器环境，在测试期间几乎像真实环境一样运行。它使用 JSDOM 创建 DOM，并将对象 window 和 document 添加到 global 中以模拟浏览器环境。

🌐 The function jsdomIt (developed in utils.ts) overrides it from vitest, and creates a pseudo-browser environment that works almost like the real deal for the duration of the test. It uses JSDOM to create a DOM, and adds objects window and document to global to mock the browser environment.

[!注意] 这个布局在 jsdomIt 测试中无法工作，因为 JSDOM 没有渲染引擎，因此不能提供伪浏览器环境。

示例：

🌐 Example :

import { ensureNodeFromSelector, jsdomIt } from './tests/util.js';

jsdomIt('should add element "thing" in the SVG', ({ svg }) => {
  // Code in this block runs in a pseudo-browser environment
  addThing(svg); // The svg item is the D3 selection of the SVG node
  const svgNode = ensureNodeFromSelector('svg'); // Retrieve the DOM node using the DOM API
  expect(svgNode.querySelector('thing')).not.toBeNull(); // Test the structure of the SVG
});

它们可以用于测试任何与 DOM 交互的方法，包括测试渲染器。不过，对于渲染器来说，还需要额外的集成测试来测试布局。

🌐 They can be used to test any method that interacts with the DOM, including for testing renderers. For renderers, additional integration testing is necessary to test the layout though.

集成 / 端到端 (E2E) 测试

🌐 Integration / End-to-End (E2E) Tests

这些用于测试图表的渲染和视觉效果。

🌐 These test the rendering and visual appearance of the diagrams.

这确保了该功能在 E2E 中的呈现将在后续的发布流程中进行审查，从而降低出错的可能性！

🌐 This ensures that the rendering of that feature in the E2E will be reviewed in the release process going forward. Less chance that it breaks!

要开始使用端到端测试：

🌐 To start working with the E2E tests:

主机

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

Docker

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

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

🌐 The rendering tests are very straightforward to create. There is a function imgSnapshotTest, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress.

在持续集成（CI）中运行时，它会对渲染的图表进行快照，并将其与上一次构建的快照进行比较，如果有差异则标记以供审查。

🌐 When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs.

这就是渲染测试的样子：

🌐 This is what a rendering test looks like:

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

更新文档

🌐 Update Documentation

提示

我们的文档位于 packages/mermaid/src/docs。关于如何编辑的详细信息请参见文档部分

如果用户无法知道有什么变化，那么你实际上并没有真正为用户“修复”任何问题；你只是让 Mermaid 感觉更加有问题。同样地，如果用户不知道你实现了一个新功能，它将永远保持未知并未被使用。

🌐 If the users have no way to know that things have changed, then you haven't really fixed anything for the users; you've just added to making Mermaid feel broken. Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused.

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

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

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

🌐 We know it can sometimes be hard to code and write user documentation.

专门为文档创建另一个问题。 你需要帮忙处理 PR，但如果觉得卡住了，务必要寻求帮助。 当写东西觉得困难时，向别人解释并让对方向你提出澄清问题，通常可以完成 80% 的工作！

🌐 Create another issue specifically for the documentation. You will need to help with the PR, but definitely ask for help if you feel stuck. When it feels hard to write stuff out, explaining it to someone and having that person ask you clarifying questions can often be 80% of the work!

有疑问时，就写下你能写的内容并提交。之后可以再进行澄清和完善。（有文档总比没有好！）

🌐 When in doubt, write up and submit what you can. It can be clarified and refined later. (With documentation, something is better than nothing!)

贡献文档

🌐 Contributing Documentation

如果文档里没有记录，就好像它从未发生过。这难道不会很令人难过吗？花了那么多心思去做的功能啊。

🌐 If it is not in the documentation, it's like it never happened. Wouldn't that be sad? With all the effort that was put into the feature?

文档在哪里？

🌐 Where is the Documentation Located?

警告

不要更改 /docs 中的文件

当提交到 packages/mermaid/src/docs 时，docs 文件夹会自动生成，不应手动编辑。

文档位于 packages/mermaid/src/docs 文件夹中。只需选择正确的部分然后开始编写即可。

🌐 Documentation is located in the packages/mermaid/src/docs folder. Just pick the right section and start typing.

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

🌐 The contents of mermaid.js.org are based on the docs from the master branch. Updates committed to the master branch are reflected in the Mermaid Docs once published.

本地运行文档网站

🌐 Running the Documentation Website Locally

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

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

🌐 Start development server for the documentation site

主机

pnpm --filter mermaid run docs:dev

或者

🌐 or

cd packages/mermaid
pnpm docs:dev

Docker

./run docs:dev

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

🌐 Open http://localhost:3333/ in your browser.

格式

🌐 Formatting

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

🌐 The documentation is written in Markdown. To get acquainted with its syntax see the GitHub Markdown help page.

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

🌐 You can use note, tip, warning and danger in triple backticks to add a note, tip, warning or danger box.

危险

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

以下是一些例子：

🌐 Here are a few examples:

```note
This is a note
```

```tip
This is a tip
```

```warning
This is a warning
```

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

信息

这是一条便条

提示

这是一个提示

警告

这是一个警告

危险

这是危险警报

导航

🌐 Navigation

如果你想对文档的 组织方式 提出更改，例如添加新章节或重新排列或重命名某个章节，你必须更新 侧边栏导航，该导航在 vitepress 配置 中定义。顶部栏 也是同样的道理。

🌐 If you want to propose changes to how the documentation is organized, such as adding a new section or re-arranging or renaming a section, you must update the sidebar navigation, which is defined in the vitepress config. The same goes for topbar.

构建文档

🌐 Build Docs

/docs 文件夹的内容是使用 GitHub Actions 构建的。

🌐 The content of /docs folder is built with GitHub Actions.

警告

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

提交你的拉取请求

🌐 Submit your pull request

INFO

Do not forget to push your changes

git push -u origin docs/2910_update-guidelines

我们通过拉取请求（PR）进行所有更改。请新建一个拉取请求。

🌐 We make all changes via Pull Requests (PRs). Open a new one.

目前我们对 PR 的命名没有遵循任何严格的规则。请给它一个具有代表性的标题和简短的描述。这里也有一个 拉取请求模板，可以帮助你完成它。

🌐 Right now we are not following any strict rules about naming PRs. Give it a representative title and short description. There is also a pull request template which will help you with it.

如果其描述中包含 magic comment，你的 PR 将会自动关联到该问题：

🌐 In case in its description contains a magic comment your PR will be automatically attached to the issue:

Resolves #<your issue ID here>

恭喜

🌐 Congratulations

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

🌐 You have successfully submitted your improvements! What is next?

• PR 将由活跃的维护者审核，他们会提供反馈并根据需要提出修改要求。
• 维护者会在必要时向 knsv 请求审查。
• 一旦拉取请求获得批准，维护者将把该拉取请求合并到 develop 分支。
• 当一个版本准备好时，将创建 release/x.x.x 分支，进行全面测试，并且 knsv 将负责发布流程。

谢谢你的帮助！

🌐 Thanks for you help!