diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 8218f31ca..9f2af0092 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -18,9 +18,9 @@ Initial setup consists of 3 main steps: flowchart LR source --> requirements --> setup - source[Get the source code] - requirements[Install the requirements] - setup[Install packages] + source[Get the Source Code] + requirements[Install the Requirements] + setup[Install Packages] ``` ### Get the Source Code @@ -47,7 +47,7 @@ cd mermaid We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. -#### Host +**Host** These are the tools we use for working with the code and documentation: @@ -56,7 +56,7 @@ These are the tools we use for working with the code and documentation: - [pnpm](https://pnpm.io/) package manager. `volta install pnpm` - [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) -#### Docker +**Docker** [Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. @@ -69,9 +69,9 @@ echo $DISPLAY If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one. -### Install packages +### Install Packages -#### Host +**Host** Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. @@ -79,7 +79,7 @@ Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't sup npx pnpm install # npx is required for first install ``` -#### Docker +**Docker** For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. @@ -118,30 +118,48 @@ pnpm test The `test` script and others are in the top-level `package.json` file. -All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) +All tests should run successfully without any errors or failures. + +> **Note** +> You might see _lint_ or _formatting_ warnings. Those are ok during this step. ## Workflow +Contributing process is very simple and strightforward: + +```mermaid + flowchart LR + + branch --> changes --> submit + branch[Checkout a New Branch] + changes[Make Changes] + submit[Submit a PR] +``` + Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. Development is done in the `develop` branch. -Once development is done we 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. - -The basic steps to start contributing code and documentation are: - ```mermaid - flowchart TB - - branch --> update --> submit --> review --> branch - branch[Checkout a new branch] - update[Make changes] - submit[Submit a PR] - review[Review and merge] +--- +config: + gitGraph: + mainBranchName: develop +--- +gitGraph LR: + commit + commit + branch "docs/2910_update-guidelines" order: 1 + commit + commit + commit + checkout develop + merge "docs/2910_update-guidelines" + commit ``` +To prepare a new version we 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 > **💡 Tip** @@ -395,11 +413,13 @@ pnpm docs:dev **Docker** - ./run docs:dev +```bash +./run docs:dev +``` Open in your browser. -### Format +### Formatting The documentation is written in Markdown. To get acquainted with its syntax [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). @@ -408,6 +428,8 @@ You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a n > **‼️ Danger** > Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. +Here are a few examples: + ````markdown ```note This is a note @@ -426,11 +448,21 @@ This is a danger alert ``` ```` +> **Note** +> This is a note + +> **💡 Tip** +> This is a tip + +> **Warning** +> This is a warning + +> **‼️ Danger** +> This is a danger alert + ### Navigation -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.** - -The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). +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](../.vitepress/config.ts). The same goes to **topbar**. ## Submit your pull request @@ -443,7 +475,7 @@ The sidebar navigation is defined in [the vitepress configuration file config.ts We make all changes via Pull Requests (PRs). Open a new one. -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](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it. +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](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it. In case in its description contains a [magic comment](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) your PR will be automatically attached to the issue: @@ -451,8 +483,6 @@ In case in its description contains a [magic comment](https://docs.github.com/en Resolves # ``` -You can edit it if needed. - ## Congratulations You have successfully submitted your improvements! What is next? diff --git a/docs/community/documentation.md b/docs/community/documentation.md index a321c882c..cd9fb277c 100644 --- a/docs/community/documentation.md +++ b/docs/community/documentation.md @@ -59,7 +59,9 @@ pnpm docs:dev **Docker** - ./run docs:dev +```bash +./run docs:dev +``` Open in your browser. diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index af5388af3..595fccf0a 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -18,9 +18,9 @@ Initial setup consists of 3 main steps: flowchart LR source --> requirements --> setup - source[Get the source code] - requirements[Install the requirements] - setup[Install packages] + source[Get the Source Code] + requirements[Install the Requirements] + setup[Install Packages] ``` ### Get the Source Code @@ -47,7 +47,7 @@ cd mermaid We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. -#### Host +**Host** These are the tools we use for working with the code and documentation: @@ -56,7 +56,7 @@ These are the tools we use for working with the code and documentation: - [pnpm](https://pnpm.io/) package manager. `volta install pnpm` - [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) -#### Docker +**Docker** [Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. @@ -69,9 +69,9 @@ echo $DISPLAY If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one. -### Install packages +### Install Packages -#### Host +**Host** Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. @@ -79,7 +79,7 @@ Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't sup npx pnpm install # npx is required for first install ``` -#### Docker +**Docker** For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. @@ -118,30 +118,48 @@ pnpm test The `test` script and others are in the top-level `package.json` file. -All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) +All tests should run successfully without any errors or failures. + +> **Note** +> You might see _lint_ or _formatting_ warnings. Those are ok during this step. ## Workflow +Contributing process is very simple and strightforward: + +```mermaid + flowchart LR + + branch --> changes --> submit + branch[Checkout a New Branch] + changes[Make Changes] + submit[Submit a PR] +``` + Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. Development is done in the `develop` branch. -Once development is done we 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. - -The basic steps to start contributing code and documentation are: - ```mermaid - flowchart TB - - branch --> update --> submit --> review --> branch - branch[Checkout a new branch] - update[Make changes] - submit[Submit a PR] - review[Review and merge] +--- +config: + gitGraph: + mainBranchName: develop +--- +gitGraph LR: + commit + commit + branch "docs/2910_update-guidelines" order: 1 + commit + commit + commit + checkout develop + merge "docs/2910_update-guidelines" + commit ``` +To prepare a new version we 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 > **💡 Tip** @@ -395,11 +413,13 @@ pnpm docs:dev **Docker** - ./run docs:dev +```bash +./run docs:dev +``` Open in your browser. -### Format +### Formatting The documentation is written in Markdown. To get acquainted with its syntax [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). @@ -408,6 +428,8 @@ You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a n > **‼️ Danger** > Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. +Here are a few examples: + ````markdown ```note This is a note @@ -426,11 +448,21 @@ This is a danger alert ``` ```` +> **Note** +> This is a note + +> **💡 Tip** +> This is a tip + +> **Warning** +> This is a warning + +> **‼️ Danger** +> This is a danger alert + ### Navigation -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.** - -The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). +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](../.vitepress/config.ts). The same goes to **topbar**. ## Submit your pull request @@ -443,7 +475,7 @@ The sidebar navigation is defined in [the vitepress configuration file config.ts We make all changes via Pull Requests (PRs). Open a new one. -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](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it. +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](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it. In case in its description contains a [magic comment](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) your PR will be automatically attached to the issue: @@ -451,8 +483,6 @@ In case in its description contains a [magic comment](https://docs.github.com/en Resolves # ``` -You can edit it if needed. - ## Congratulations You have successfully submitted your improvements! What is next? diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 59fb3a941..550adc6d3 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -59,7 +59,9 @@ pnpm docs:dev **Docker** - ./run docs:dev +```bash +./run docs:dev +``` Open in your browser.