Mermaid

外觀

使用 Mermaid Chart 中的視覺化編輯器設計和建立圖表

Mermaid 貢獻指南 ​

您決定參與開發？歡迎！

我們正努力讓您的指南盡可能明確和詳細。

初始設定 ​

初始設定包含 3 個主要步驟

取得原始碼 ​

在 GitHub 中，當您要進行變更並提交 pull request 時，首先fork 一個 mermaid 儲存庫。

然後您將一份副本 clone 到您的本機開發機器（例如，您編寫程式碼的地方），以製作一份包含所有檔案的副本來使用。

提示

這是一份 GitHub 文件，概述了整個過程.

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

將儲存庫 clone 到您的開發機器後，請變更到 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 是否正常運作以及是否已正確 clone 儲存庫

主機

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

我們知道有時很難同時編寫程式碼和撰寫使用者文件。

專門為文件建立另一個 issue。您需要協助 PR，但如果您感到卡住，請務必尋求協助。當您覺得很難寫出來時，向某人解釋並讓該人問您澄清問題通常可以完成 80% 的工作！

如有疑問，請撰寫並提交您可以做的。稍後可以澄清和完善。(對於文件，有總比沒有好！)

貢獻文件 ​

如果它不在文件中，那就好像它從未發生過一樣。那不是很令人難過嗎？付出了這麼多努力來完成這個功能？

文件位於何處？ ​

警告

請勿變更 /docs 中的檔案

提交到 packages/mermaid/src/docs 時，將自動產生 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 建置的。

警告

為了允許自動編譯文件頁面，您必須先在您的 fork 上啟用 Github Actions

提交您的提取請求 ​

資訊

不要忘記推送您的變更

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

我們透過提取請求 (PR) 進行所有變更。開啟一個新的。

目前我們沒有遵循任何關於命名 PR 的嚴格規則。給它一個具有代表性的標題和簡短描述。還有一個 提取請求範本，可以幫助您完成此操作。

如果它的描述包含一個魔術註解，您的 PR 將會自動附加到該 issue

markdown
Resolves #<your issue ID here>

恭喜 ​

您已成功提交您的改進！下一步是什麼？

  • PR 將由積極的維護者審查，他們將提供回饋並根據需要請求變更。
  • 如有必要，維護者將請求 knsv 的審查。
  • 一旦 PR 獲得批准，維護者將把 PR 合併到 develop 分支中。
  • 當發佈版本準備就緒時，將建立 release/x.x.x 分支，進行廣泛測試，knsv 將負責發佈流程。

感謝您的幫助！