GitHub/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-01-14 06:43:25 +08:00
Code Issues Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
nirname 2024-01-05 13:56:36 +00:00
parent 9aaf63139a
commit 9ccb340d63
7 changed files with 2 additions and 488 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/community/setup.md
View File

@ -1,115 +0,0 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/setup.md](../../packages/mermaid/src/docs/community/setup.md).
# Initial Setup
Initial setup consists of 3 main steps:
```mermaid
flowchart LR
source --> requirements --> setup
source[Get the source code]
requirements[Install the requirements]
setup[Install packages]
```
## Get the Source Code
In GitHub, you first **fork** a 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.
[Fork mermaid](https://github.com/mermaid-js/mermaid/fork) to start contributing to the main project and its documentation, or [search for other repositories](https://github.com/orgs/mermaid-js/repositories).
[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
```bash
git clone git@github.com/your-fork/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
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:
- [volta](https://volta.sh/) to manage node versions.
- [Node.js](https://nodejs.org/en/). `volta install node`
- [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
[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need.
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
```
If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one.
## Install packages
### Host
Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet.
```bash
npx pnpm install # npx is required for first install
```
### Docker
For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands.
Make sure that `./run` script is executable:
```bash
chmod +x run
```
> **💡 Tip**
> To get detailed help simply type `./run` or `./run help`.
>
> It also has short _Development quick start guide_ embedded.
```bash
./run pnpm install # Install packages
```
## 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.
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
```
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.)

128
docs/community/workflow.md
View File

@ -1,128 +0,0 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/workflow.md](../../packages/mermaid/src/docs/community/workflow.md).
# Workflow
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.
```mermaid
flowchart TB
branch --> update --> submit --> review --> branch
branch[Checkout a new branch]
update[Make changes]
submit[Submit a PR]
review[Review and merge]
```
## Checkout a New Branch
> **💡 Tip**
> All new work should be based on the `develop` branch.
Make sure you have the most up-to-date version of the `develop` branch.
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](https://github.com/mermaid-js/mermaid/blob/develop/.github/pr-labeler.yml)
- The first part is the **type** of change: a `feature`, `bug`, `chore`, `docs`
- followed by a **slash** (`/`),which helps to group like types together in many git tools
- followed by the **issue number**, e.g. `2910`
- followed by an **underscore** (`_`)
- followed by a **short description** with dashes (`-`) or underscores (`_`) instead of spaces
```mermaid
flowchart LR
feature --> slash
bug --> slash
chore --> slash
docs --> slash
slash --> 2945 --> underscore
slash --> 1123 --> underscore
underscore --> short_description_1
underscore --> short_description_2
underscore["_"]
slash["/"]
short_description_1["state-diagram-new-arrow-florbs"]
short_description_2["fix_random_ugly_red_text"]
```
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.
> **Note**
> A new feature described in issue 2945 that adds a new arrow type called 'florbs' to state diagrams
>
> `feature/2945_state-diagram-new-arrow-florbs`
> **💡 Tip**
> A bug described in issue 1123 that causes random ugly red text in multiple diagram types
>
> `bug/1123_fix_random_ugly_red_text`
## Make changes
Source code and the documentation are located \[`packages/mermaid`]\((<https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid>) folder.
You may need to update both, depending on your task.
Read our guides on [how to contribute to code](./code.md) and [how to contribute to documentation](./documentation.md).
## Submit your pull request
> **Note**
> Do not forget to push your changes
>
> ```bash
> git push -u origin docs/2910_update-contributing-guidelines
> ```
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.
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:
```markdown
Resolves #<your issue ID here>
```
You can edit it if needed.
## Congratulations
You have successfully submitted your improvements! What is next?
- PRs will be reviewed by active maintainers, who will provide feedback and request changes as needed.
- The maintainers will request a review from _knsv_, if necessary.
- Once the PR is approved, the maintainers will merge the PR into the `develop` branch.
- 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.
_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs.

2
docs/config/usage.md
View File

@ -20,7 +20,7 @@ Please note that you can switch versions through the dropdown box at the top rig
For the majority of users, Using the [Live Editor](https://mermaid.live/) would be sufficient, however you may also opt to deploy mermaid as a dependency or using the [Mermaid API](./setup/README.md).
We have compiled some Video [Tutorials](./Tutorials.md) on how to use the Mermaid Live Editor.
We have compiled some Video [Tutorials](../comminuty/tutorials.md) on how to use the Mermaid Live Editor.
### Installing and Hosting Mermaid on a Webpage

2
docs/contributing/contributing.md
View File

@ -355,7 +355,7 @@ it('should render forks and joins', () => {
### Update Documentation
> **💡 Tip**
> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](#documentation)
> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](documentation)
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.

115
docs/contributing/setup.md
View File

@ -1,115 +0,0 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/setup.md](../../packages/mermaid/src/docs/contributing/setup.md).
# Initial Setup
Initial setup consists of 3 main steps:
```mermaid
flowchart LR
source --> requirements --> setup
source[Get the source code]
requirements[Install the requirements]
setup[Install packages]
```
## Get the Source Code
In GitHub, you first **fork** a 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.
[Fork mermaid](https://github.com/mermaid-js/mermaid/fork) to start contributing to the main project and its documentation, or [search for other repositories](https://github.com/orgs/mermaid-js/repositories).
[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
```bash
git clone git@github.com/your-fork/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
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:
- [volta](https://volta.sh/) to manage node versions.
- [Node.js](https://nodejs.org/en/). `volta install node`
- [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
[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need.
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
```
If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one.
## Install packages
### Host
Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet.
```bash
npx pnpm install # npx is required for first install
```
### Docker
For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands.
Make sure that `./run` script is executable:
```bash
chmod +x run
```
> **💡 Tip**
> To get detailed help simply type `./run` or `./run help`.
>
> It also has short _Development quick start guide_ embedded.
```bash
./run pnpm install # Install packages
```
## 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.
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
```
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.)

128
docs/contributing/workflow.md
View File

@ -1,128 +0,0 @@
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/workflow.md](../../packages/mermaid/src/docs/contributing/workflow.md).
# Workflow
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.
```mermaid
flowchart TB
branch --> update --> submit --> review --> branch
branch[Checkout a new branch]
update[Make changes]
submit[Submit a PR]
review[Review and merge]
```
## Checkout a New Branch
> **💡 Tip**
> All new work should be based on the `develop` branch.
Make sure you have the most up-to-date version of the `develop` branch.
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](https://github.com/mermaid-js/mermaid/blob/develop/.github/pr-labeler.yml)
- The first part is the **type** of change: a `feature`, `bug`, `chore`, `docs`
- followed by a **slash** (`/`),which helps to group like types together in many git tools
- followed by the **issue number**, e.g. `2910`
- followed by an **underscore** (`_`)
- followed by a **short description** with dashes (`-`) or underscores (`_`) instead of spaces
```mermaid
flowchart LR
feature --> slash
bug --> slash
chore --> slash
docs --> slash
slash --> 2945 --> underscore
slash --> 1123 --> underscore
underscore --> short_description_1
underscore --> short_description_2
underscore["_"]
slash["/"]
short_description_1["state-diagram-new-arrow-florbs"]
short_description_2["fix_random_ugly_red_text"]
```
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.
> **Note**
> A new feature described in issue 2945 that adds a new arrow type called 'florbs' to state diagrams
>
> `feature/2945_state-diagram-new-arrow-florbs`
> **💡 Tip**
> A bug described in issue 1123 that causes random ugly red text in multiple diagram types
>
> `bug/1123_fix_random_ugly_red_text`
## Make changes
Source code and the documentation are located \[`packages/mermaid`]\((<https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid>) folder.
You may need to update both, depending on your task.
Read our guides on [how to contribute to code](./code.md) and [how to contribute to documentation](./documentation.md).
## Submit your pull request
> **Note**
> Do not forget to push your changes
>
> ```bash
> git push -u origin docs/2910_update-contributing-guidelines
> ```
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.
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:
```markdown
Resolves #<your issue ID here>
```
You can edit it if needed.
## Congratulations
You have successfully submitted your improvements! What is next?
- PRs will be reviewed by active maintainers, who will provide feedback and request changes as needed.
- The maintainers will request a review from _knsv_, if necessary.
- Once the PR is approved, the maintainers will merge the PR into the `develop` branch.
- 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.
_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs.

0
docs/config/img/python-mermaid-integration.png → docs/ecosystem/img/python-mermaid-integration.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB