Update docs
This commit is contained in:
nirname
parent
9aaf63139a
commit
9ccb340d63
|
|
@ -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.)
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.)
|
||||
|
|
@ -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.
|
||||
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
Loading…
Reference in New Issue