Mermaid 中文网

主题

体验 Mermaid 在线编辑器！

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 中，当你要进行更改并提交拉取请求时，首先要 fork 一个 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.

提示

Here is a GitHub document that gives an overview of the process。

bash
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)

bash
cd mermaid

安装要求 ​

¥Install Requirements

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

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

主机

¥Host

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

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

以下命令必须足够：

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

bash
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。这几乎就是你所需要的一切。

¥Install Docker. And that is pretty much all you need.

或者，要在 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:

bash
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

主机

¥Host

安装软件包：

¥Install packages:

bash
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:

bash
chmod +x run

提示

要获得详细帮助，只需输入 ./run 或 ./run help。其中还嵌入了简短的 _ 开发快速入门指南 _。

然后安装软件包：

¥Then install packages:

bash
./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:

主机

¥Host

bash
pnpm test

Docker

bash
./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:

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

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

¥Create a new branch for your work:

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

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

¥We use the following naming convention for branches:

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

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

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

  • 第一部分是更改的类型：feature、bug、chore、docs

    ¥The first part is the type of change: a feature, bug, chore, docs

  • 后跟斜线 (/)，这有助于在许多 git 工具中将相似的类型分组在一起

    ¥followed by a slash (/),which helps to group like types together in many git tools

  • 后跟问题编号，例如 2910

    ¥followed by the issue number, e.g. 2910

  • 后跟下划线 (_)

    ¥followed by an underscore (_)

  • 后跟简短描述，请使用破折号 (-) 或下划线 (_) 代替空格

    ¥followed by a short description with dashes (-) or underscores (_) instead of spaces

如果你的工作只针对一种图表类型，最好将图表类型放在描述的开头。这将帮助我们按图表类型组织发行说明。

¥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

主机

¥Host

bash
pnpm run build

Docker

bash
./run build

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

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

本地运行 Mermaid ​

¥Running Mermaid Locally

主机

¥Host

bash
pnpm run dev

Docker

bash
./run dev

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

¥After starting the dev server open http://localhost:9000 in your browser.

现在你可以进行更改了！

¥Now you are ready to make your changes!

进行修改 ​

¥Make Changes

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

¥Have a look at http://localhost:9000. There is a list of demos that can be used to see and test your changes.

如果你需要特定的图表，你可以在 /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 库并自动重新加载页面。

¥That will be served at http://localhost:9000/dev/your-file-name.html. After making code changes, the dev server will rebuild the mermaid library and automatically reload the page.

根据需要在 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.

如果你正在修复错误，你应该添加测试以确保你的代码确实修复了错误，并指定/描述代码的功能，并确保错误不会再次发生。（如果之前针对这种情况进行过测试，这个 bug 根本就不会发生。）如果现有测试不准确，你可能需要进行更改。

¥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 renderers. (The renderers are tested with integration tests.)

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

¥We use Vitest to run unit tests.

主机

¥Host

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

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

sh
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:

sh
pnpm test:watch

Docker

使用 Docker 时，请在命令前添加 ./run:

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

sh
./run pnpm test

集成/端到端 (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!

要开始进行 E2E 测试：

¥To start working with the E2E tests:

主机

¥Host

  • 运行 pnpm dev 以启动开发服务器

    ¥Run pnpm dev to start the dev server

  • 运行 pnpm cypress:open 启动 Cypress

    ¥Start Cypress by running pnpm cypress:open

Docker

  • 为 x11 服务器 xhost +local: 启用本地连接

    ¥Enable local connections for x11 server xhost +local:

  • 运行 ./run pnpm dev 以启动开发服务器

    ¥Run ./run pnpm dev to start the dev server

  • 运行 ./run pnpm cypress:open --project . 启动 Cypress

    ¥Start Cypress by running ./run pnpm cypress:open --project .

渲染测试的创建非常简单。有一个函数 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:

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

更新文档 ​

¥Update Documentation

提示

我们的文档在 packages/mermaid/src/docs 中管理。有关如何编辑的详细信息，请参阅 documentation section

如果用户无法得知内容已更改，则说明你实际上并未为用户修复任何问题；你刚刚添加了 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>+)。发布时，它将自动替换为当前版本号。

¥The documentation has to be updated for users to know that things have been changed and added! If you are adding a new feature, add (v<MERMAID_RELEASE_VERSION>+) in the title or description. It will be replaced automatically with the current version number when the release happens.

例如：# Feature Name (v<MERMAID_RELEASE_VERSION>+)

¥eg: # Feature Name (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 提供支持。

¥The mermaid documentation site is powered by Vitepress.

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

¥Start development server for the documentation site

主机

¥Host

bash
pnpm --filter mermaid run docs:dev

or

bash
cd packages/mermaid
pnpm docs:dev

Docker

bash
./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.

DANGER

Do not use vitepress specific markdown syntax ::: warning as it will not be processed correctly.

以下是一些示例：

¥Here are a few examples:

markdown
```note 信息
这是一条注释
```

```tip 提示
这是一条提示
```

```warning 警告
这是一条警告
```

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

信息

这是一条注释

提示

这是一条提示

警告

这是一条警告

DANGER

This is a danger alert

¥Navigation

如果你想对文档的组织方式提出修改建议，例如添加新章节、重新排列或重命名章节，则必须更新侧边栏导航，该导航在 vitepress 配置 中定义。topbar 也是如此。

¥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 to topbar.

构建文档 ​

¥Build Docs

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

¥The content of /docs folder is built with Github Actions.

警告

为了允许自动编译文档页面，你必须先在你的 fork 上启用 Github Actions。

提交拉取请求 ​

¥Submit your pull request

INFO

Do not forget to push your changes

bash
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.

如果描述中包含 神奇的评论，你的 PR 将自动附加到问题中：

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

markdown
Resolves #<your issue ID here>

恭喜 ​

¥Congratulations

你已成功提交改进！下一步是什么？

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

  • PR 将由活跃的维护人员审核，他们将根据需要提供反馈并请求更改。

    ¥PRs will be reviewed by active maintainers, who will provide feedback and request changes as needed.

  • 如有必要，维护人员将向 knsv 请求审核。

    ¥The maintainers will request a review from knsv, if necessary.

  • PR 获得批准后，维护人员会将 PR 合并到 develop 分支。

    ¥Once the PR is approved, the maintainers will merge the PR into the develop branch.

  • 发布准备就绪后，将创建 release/x.x.x 分支，进行全面测试，并由 knsv 负责发布流程。

    ¥When a release is ready, the release/x.x.x branch will be created, extensively tested and knsv will be in charge of the release process.

感谢你的帮助！

¥Thanks for you help!