Mermaidコントリビューティングガイド

開発に参加することを決めた皆さん、ようこそ！

可能な限り明確で詳細なガイドラインを作成しようと努めています。

初期設定

初期設定は3つの主要な手順で構成されます。

ソースコードの取得

GitHubで、まず変更を加えてプルリクエストを送信する場合に**Mermaidリポジトリをフォーク**します。

次に、作業するすべてのファイルを含むコピーを作成するために、ローカルの開発マシン（コードを作成する場所など）にコピーを**クローン**します。

ヒント

このプロセスを概説したGitHubドキュメントを以下に示します。.

bash

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

リポジトリを開発マシンにクローンしたら、`mermaid`プロジェクトフォルダ（Mermaidプロジェクトリポジトリの最上位ディレクトリ）に移動します。

bash

cd mermaid

要件のインストール

**Docker環境内での開発**と**ホスト設定**の両方をサポートしています。好みに合わせて選択できます。

ホスト

コードとドキュメントの作業に使用しているツールを以下に示します。

Node.js.
pnpmパッケージマネージャー。

開始するには、次のコマンドで十分です。

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を使用しています。

ホスト

次のコマンドを使用して単体テストを実行できます。

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**を起動します。

レンダリングテストの作成は非常に簡単です。テキスト形式のダイアグラムとmermaidオプションを受け取るimgSnapshotTestという関数があり、Cypressでそのダイアグラムをレンダリングします。

CIで実行すると、レンダリングされたダイアグラムのスナップショットを取得し、前回のビルドのスナップショットと比較し、違いがあればレビューのためにフラグを立てます。

レンダリングテストは次のようになります。

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

      state join_state &lt;&lt;join&gt;&gt;
      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ヘルプページを参照してください。

3つのバッククォートで囲んで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を作成してください。

現在、PRの命名に関する厳格なルールはありません。適切なタイトルと短い説明を付けてください。プルリクエストテンプレートも用意されていますので、ご利用ください。

説明にマジックコメントが含まれている場合、PRは自動的に課題に関連付けられます。

markdown

Resolves #<your issue ID here>

おめでとう

改善点を正常に送信しました！次に何をするべきでしょうか？

PRはアクティブなメンテナーによってレビューされ、必要に応じてフィードバックと変更要求が提供されます。
必要に応じて、メンテナーはknsvからのレビューを依頼します。
PRが承認されると、メンテナーはPRをdevelopブランチにマージします。
リリースの準備が整うと、release/x.x.xブランチが作成され、広範囲にテストされ、knsvがリリースプロセスを担当します。

ご協力ありがとうございます！

Mermaidコントリビューティングガイド ​

初期設定 ​

ソースコードの取得 ​

要件のインストール ​

パッケージのインストール ​

すべてが正常に動作することを確認する ​

ワークフロー ​

新しいブランチのチェックアウト ​

コードへのコントリビューション ​

コードはどこにありますか？ ​

Mermaidのローカル実行 ​

変更を加える ​

テストの記述 ​

単体テスト ​

統合/エンドツーエンド（E2E）テスト ​

ドキュメントの更新 ​

ドキュメントへの貢献 ​

ドキュメントの場所 ​

ドキュメントウェブサイトのローカル実行 ​

書式設定 ​

ナビゲーション ​

ドキュメントのビルド ​

プルリクエストの送信 ​

おめでとう ​

Mermaidコントリビューティングガイド

初期設定

ソースコードの取得

要件のインストール

パッケージのインストール

すべてが正常に動作することを確認する

ワークフロー

新しいブランチのチェックアウト

コードへのコントリビューション

コードはどこにありますか？

Mermaidのローカル実行

変更を加える

テストの記述

単体テスト

統合/エンドツーエンド（E2E）テスト

ドキュメントの更新

ドキュメントへの貢献

ドキュメントの場所

ドキュメントウェブサイトのローカル実行

書式設定

ナビゲーション

ドキュメントのビルド

プルリクエストの送信

おめでとう