Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: #5751 docs: Contribution flow correction: #5752

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
+129 −113
Open

fix: #5751 docs: Contribution flow correction: #5752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 83 additions & 40 deletions docs/community/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,15 @@ We are trying to make our guidelines for you as explicit and detailed as possibl

Initial setup consists of 3 main steps:

```mermaid-example
flowchart LR
source --> requirements --> setup

source[Get the Source Code]
requirements[Install the Requirements]
setup[Install Packages]
```

```mermaid
flowchart LR
source --> requirements --> setup
Expand All @@ -29,7 +38,7 @@ In GitHub, you first [**fork a mermaid repository**](https://github.com/mermaid-

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.

> **💡 Tip** > [Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
> \[!TIP] > [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 [email protected]/your-fork/mermaid
Expand Down Expand Up @@ -94,7 +103,7 @@ Make sure that `./run` script is executable:
chmod +x run
```

> **💡 Tip**
> \[!TIP]
> To get detailed help simply type `./run` or `./run help`.
>
> It also has short _Development quick start guide_ embedded.
Expand Down Expand Up @@ -127,13 +136,22 @@ The `test` script and others are in the top-level `package.json` file.

All tests should run successfully without any errors or failures.

> **Note**
> \[!NOTE]
> You might see _lint_ or _formatting_ warnings. Those are ok during this step.

## Workflow

Contributing process is very simple and straightforward:

```mermaid-example
flowchart LR

branch --> changes --> submit
branch[Checkout a New Branch]
changes[Make Changes]
submit[Submit a PR]
```

```mermaid
flowchart LR

Expand All @@ -147,6 +165,24 @@ Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspir

Development is done in the `develop` branch.

```mermaid-example
---
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
```

```mermaid
---
config:
Expand All @@ -169,7 +205,7 @@ To prepare a new version for release the maintainers create a `release/vX.X.X` b

## Checkout a New Branch

> **💡 Tip**
> \[!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.
Expand Down Expand Up @@ -201,6 +237,24 @@ You can always check current [configuration of labelling and branch prefixes](ht
- followed by an **underscore** (`_`)
- followed by a **short description** with dashes (`-`) or underscores (`_`) instead of spaces

```mermaid-example
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"]
```

```mermaid
flowchart LR
feature --> slash
Expand All @@ -221,12 +275,12 @@ flowchart LR

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**
> \[!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**
> \[!TIP]
> A bug described in issue 1123 that causes random ugly red text in multiple diagram types
>
> `bug/1123_fix_random_ugly_red_text`
Expand Down Expand Up @@ -363,7 +417,7 @@ it('should render forks and joins', () => {

### Update Documentation

> **💡 Tip**
> \[!TIP]
> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](#contributing-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.
Expand All @@ -388,7 +442,7 @@ If it is not in the documentation, it's like it never happened. Wouldn't that be

### Where is the Documentation Located?

> **Warning**
> \[!WARNING]
> DO NOT CHANGE FILES IN `/docs`
>
> The `docs` folder will be automatically generated when committing to `packages/mermaid/src/docs` and **should not** be edited manually.
Expand Down Expand Up @@ -442,42 +496,31 @@ Open <http://localhost:3333/> in your browser.

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

You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a note, tip, warning or danger box.
You can use `[!NOTE]`, `[!TIP]`, `[!WARNING]` and `[!CAUTION]` to add a note, tip, warning or danger box.

> **‼️ Danger**
> \[!NOTE] > [See syntax references](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)

> \[!CAUTION]
> 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
```
> [!NOTE]
> Useful information that users should know, even when skimming content.

```tip
This is a tip
```

```warning
This is a warning
```

```danger
This is a danger alert
```
````
> [!TIP]
> Helpful advice for doing things better or more easily.

> **Note**
> This is a note
> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> **💡 Tip**
> This is a tip
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> **Warning**
> This is a warning

> **‼️ Danger**
> This is a danger alert
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```

### Navigation

Expand All @@ -487,17 +530,17 @@ If you want to propose changes to how the documentation is _organized_, such as

The content of `/docs` folder is built with Github Actions.

> **Warning**
> \[!WARNING]
> So as to allow automatic compilation of documentation pages you have to enable Github Actions on your fork first

## Submit your pull request

> **Note**
> \[!NOTE]
> Do not forget to push your changes
>
> ```bash
> git push -u origin docs/2910_update-guidelines
> ```

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

We make all changes via Pull Requests (PRs). Open a new one.

Expand Down
Loading
Loading