mirrors
/
mermaid
mirror of https://github.com/mermaid-js/mermaid.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Contribution guidelines rework

This commit is contained in:
Nikolay Rozhkov 2023-12-19 02:48:22 +03:00
parent 7b6764da20
commit 2f3f76fa24
8 changed files with 206 additions and 328 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
CONTRIBUTING.md
View File

@ -1,78 +0,0 @@
# Contributing
Please read in detail about how to contribute documentation and code on the [Mermaid documentation site.](https://mermaid-js.github.io/mermaid/#/development)
---
# Mermaid contribution cheat-sheet
## Requirements
- [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`
## Development Installation
If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js:
```bash
git clone git@github.com:mermaid-js/mermaid.git
cd mermaid
```
Install required packages:
```bash
# npx is required for first install as volta support for pnpm is not added yet.
npx pnpm install
pnpm test # run unit tests
pnpm dev # starts a dev server
```
Open <http://localhost:9000> in your browser after starting the dev server.
You can also duplicate the `example.html` file in `demos/dev`, rename it and add your own mermaid code to it.
That will be served at <http://localhost:9000/dev/your-file-name.html>.
### Docker
If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands:
```bash
./run install # npx pnpm install
./run test # pnpm test
```
## Testing
```bash
# Run unit test
pnpm test
# Run unit test in watch mode
pnpm test:watch
# Run E2E test
pnpm e2e
# Debug E2E tests
pnpm dev
pnpm cypress:open # in another terminal
```
## Branch name format:
```text
[feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces]
```
eg: `feature/2945_state-diagram-new-arrow-florbs`, `bug/1123_fix_random_ugly_red_text`
## Documentation
Documentation is necessary for all non bugfix/refactoring changes.
Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs)
**_DO NOT CHANGE FILES IN `/docs` MANUALLY_**
The `/docs` folder will be rebuilt and committed as part of a pre-commit hook.
[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE)

1
CONTRIBUTING.md Symbolic link
View File

@ -0,0 +1 @@
./packages/mermaid/src/docs/community/contributing.md

97
packages/mermaid/src/docs/community/code.md
View File

@ -1,71 +1,41 @@
# Contributing Code
The basic steps for contributing code are:
Code it the heart of every software project. We strive to make it better. Who if not us?
```mermaid
graph LR
git --> codeTest --> doc --> submit --> review
## Where is the code located?
git[1. Checkout a git branch]
codeTest[2. Write tests and code]
doc[3. Update documentation]
submit[4. Submit a PR]
review[5. Review and merge]
The core of Mermaid is located under `packages/mermaid/src`.
## Running Mermaid Locally
**Host**
```bash
npx pnpm run dev
```
1. **Create** and checkout a git branch and work on your code in the branch
2. Write and update **tests** (unit and perhaps even integration (e2e) tests) (If you do TDD/BDD, the order might be different.)
3. **Let users know** that things have changed or been added in the documents! This is often overlooked, but _critical_
4. **Submit** your code as a _pull request_.
5. Maintainers will **review** your code. If there are no changes necessary, the PR will be merged. Otherwise, make the requested changes and repeat.
**Docker**
## 1. Checkout a git branch
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.
**All new work should be based on the `develop` branch.**
**When you are ready to do work, always, ALWAYS:**
1. Make sure you have the most up-to-date version of the `develop` branch. (fetch or pull to update it)
2. Check out the `develop` branch
3. Create a new branch for your work. Please name the branch following our naming convention below.
We use the following naming convention for branches:
```txt
[feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces]
```bash
./run dev
```
You can always check current [configuration of labelling and branch prefixes](https://github.com/mermaid-js/mermaid/blob/develop/.github/pr-labeler.yml)
After starting the dev server open <http://localhost:9000> in your browser.
- The first part is the **type** of change: a feature, bug, chore, or documentation change ('docs')
- followed by a _slash_ (which helps to group like types together in many git tools)
- followed by the **issue number**
- followed by an _underscore_ ('\_')
- followed by a short text description (but use dashes ('-') or underscores ('\_') instead of spaces)
Now you are ready to make your changes!
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: it will help us keep changes for a diagram type together.
## Make Changes
```tip
**Ex: A new feature described in issue 2945 that adds a new arrow type called 'florbs' to state diagrams**
Have a look at <http://localhost:9000>. There is a list of demos that can be used to see and test your changes.
`feature/2945_state-diagram-new-arrow-florbs`
```
If you need a specific diagram, you can duplicate the `example.html` file in `/demos/dev` and add your own mermaid code to your copy.
```tip
**Ex: A bug described in issue 1123 that causes random ugly red text in multiple diagram types**
That will be served at <http://localhost:9000/dev/your-file-name.html>.
After making code changes, the dev server will rebuild the mermaid library. You will need to reload the browser page yourself to see the changes. (PRs for auto reload are welcome!)
`bug/1123_fix_random_ugly_red_text`
```
Edit files in `packages/mermaid/src` as required.
## 2. Write Tests
## Write Tests
Tests ensure that each function, module, or part of code does what it says it will do. This is critically
important when other changes are made to ensure that existing code is not broken (no regression).
@ -138,11 +108,13 @@ it('should render forks and joins', () => {
```
**_[TODO - running the tests against what is expected in development. ]_**
**_[TODO - how to generate new screenshots]_**
....
## 3. Update Documentation
## Update Documentation
```tip
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.
@ -154,23 +126,8 @@ eg: `# Feature Name (v<MERMAID_RELEASE_VERSION>+)`
We know it can sometimes be hard to code _and_ write user documentation.
Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [Contributing Documentation](#contributing-documentation) section.
Create another issue specifically for the documentation.
You will need to help with the PR, but definitely ask for help if you feel stuck.
When it feels hard to write stuff out, explaining it to someone and having that person ask you clarifying questions can often be 80% of the work!
When in doubt, write up and submit what you can. It can be clarified and refined later. (With documentation, something is better than nothing!)
## 4. Submit your pull request
**[TODO - PR titles should start with (fix | feat | ....)]**
We make all changes via Pull Requests (PRs). As we have many Pull Requests from developers new to Mermaid, we have put in place a process wherein _knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs.
- 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.
**Reminder: Pull Requests should be submitted to the develop branch.**

81
packages/mermaid/src/docs/community/contributing.md Normal file
View File

@ -0,0 +1,81 @@
---
# Old Contributing Guide
Please read in detail about how to contribute documentation and code on the [Mermaid documentation site.](https://mermaid-js.github.io/mermaid/#/development)
---
# Mermaid contribution cheat-sheet
## Requirements
- [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`
## Development Installation
If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js:
```bash
git clone git@github.com:mermaid-js/mermaid.git
cd mermaid
```
Install required packages:
```bash
# npx is required for first install as volta support for pnpm is not added yet.
npx pnpm install
pnpm test # run unit tests
pnpm dev # starts a dev server
```
Open <http://localhost:9000> in your browser after starting the dev server.
You can also duplicate the `example.html` file in `demos/dev`, rename it and add your own mermaid code to it.
That will be served at <http://localhost:9000/dev/your-file-name.html>.
### Docker
If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands:
```bash
./run install # npx pnpm install
./run test # pnpm test
```
## Testing
```bash
# Run unit test
pnpm test
# Run unit test in watch mode
pnpm test:watch
# Run E2E test
pnpm e2e
# Debug E2E tests
pnpm dev
pnpm cypress:open # in another terminal
```
## Branch name format:
```text
[feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces]
```
eg: `feature/2945_state-diagram-new-arrow-florbs`, `bug/1123_fix_random_ugly_red_text`
## Documentation
Documentation is necessary for all non bugfix/refactoring changes.
Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs)
**_DO NOT CHANGE FILES IN `/docs` MANUALLY_**
The `/docs` folder will be rebuilt and committed as part of a pre-commit hook.
[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE)

106
packages/mermaid/src/docs/community/docker-setup.md
View File

@ -1,106 +0,0 @@
# Initial setup with Docker
> The following documentation describes how to work with Mermaid in a Docker environment.
> There's also a [host installation guide](../community/setup.md)
> if you prefer to work without a Docker environment.
Initial setup consists of 3 main steps::
```mermaid-nocode
flowchart LR
source --> requirements --> setup
source[Get the source code]
requirements[Install the requirements]
setup[Setup and launch]
```
## 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)
## Technical Requirements
> The following documentation describes how to work with Mermaid in a Docker environment.
> There's also a [host installation guide](../community/setup.md)
> if you prefer to work without a Docker environment.
[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.
## Setup and Launch
### Switch to project
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
```
### Make `./run` executable
For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands.
Ensure `./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.
```
### Install packages
```bash
./run pnpm install # Install packages
```
### Launch
```bash
./run dev
```
Now you are ready to make your changes! Edit whichever files in `src` as required.
Open <http://localhost:9000> in your browser, after starting the dev server.
There is a list of demos that can be used to see and test your changes.
If you need a specific diagram, you can duplicate the `example.html` file in `/demos/dev` and add your own mermaid code to your copy.
That will be served at <http://localhost:9000/dev/your-file-name.html>.
After making code changes, the dev server will rebuild the mermaid library. You will need to reload the browser page yourself to see the changes. (PRs for auto reload are welcome!)
## Verify Everything is Working
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:
```bash
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.)

56
packages/mermaid/src/docs/community/documentation.md
View File

@ -1,13 +1,8 @@
# Contributing to Documentation
# Contributing Documentation
If it is not in the documentation, it's like it never happened. Wouldn't that be sad? With all the effort that was put into the feature?
The documentation is written in Markdown. It is located in the [`packages/mermaid/src/docs`](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs) folder and organized according to relevant subfolder. Just pick the right section and start typing.
The contents of [mermaid.js.org](https://mermaid.js.org/) are based on the docs from the `master` branch. Updates committed to the `master` branch are reflected in the [Mermaid Docs](https://mermaid.js.org/) once published.
## How to Contribute
## Where is the Documentation Located?
```warning
DO NOT CHANGE FILES IN `/docs`
@ -15,25 +10,47 @@ 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.
```
It is located in the [`packages/mermaid/src/docs`](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs) folder. Just pick the right section and start typing.
The contents of [mermaid.js.org](https://mermaid.js.org/) are based on the docs from the `master` branch. Updates committed to the `master` branch are reflected in the [Mermaid Docs](https://mermaid.js.org/) once published.
```mermaid
flowchart LR
classDef default fill:#fff,color:black,stroke:black
source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"]
```
## Runing the Documentation Website
## Running the Documentation Website Locally
**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).**
To run the documentation site locally:
Start development server for the documentation site
1. Run `pnpm --filter mermaid run docs:dev` to start the dev server. (Or `pnpm docs:dev` inside the `packages/mermaid` directory.)
2. Open [http://localhost:3333/](http://localhost:3333/) in your browser.
**Host**
```bash
pnpm --filter mermaid run docs:dev
```
or
### Markdown extensions
```
cd packages/mermaid
pnpm docs:dev
```
**Docker**
```
./run docs:dev
```
Open [http://localhost:3333/](http://localhost:3333/) in your browser.
## Format
The documentation is written in Markdown.
You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a note, tip, warning or danger box.
Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly.
@ -56,11 +73,8 @@ Danger content
```
````
Markdown is used to format the text, for more information about Markdown [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).
To edit Docs on your computer:
_[TODO: need to keep this in sync with [check out a git branch in Contributing Code above](#1-checkout-a-git-branch) ]_
1. Create a fork of the develop branch to work on.
@ -69,16 +83,6 @@ _[TODO: need to keep this in sync with [check out a git branch in Contributing C
4. Commit changes to your branch and push it to GitHub (which should create a new branch).
5. Create a Pull Request from the branch of your fork.
To edit Docs on GitHub:
1. Login to [GitHub.com](https://www.github.com).
2. Navigate to [packages/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs) in the mermaid-js repository.
3. To edit a file, click the pencil icon at the top-right of the file contents panel.
4. Describe what you changed in the **Propose file change** section, located at the bottom of the page.
5. Submit your changes by clicking the button **Propose file change** at the bottom (by automatic creation of a fork and a new branch).
6. Visit the Actions tab in Github, `https://github.com/<Your Username>/mermaid/actions` and enable the actions for your fork. This will ensure that the documentation is built and updated in your fork.
7. Create a Pull Request of your newly forked branch by clicking the green **Create Pull Request** button.
## Documentation organization: Sidebar 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.**

9
packages/mermaid/src/docs/community/intro.md
View File

@ -25,16 +25,15 @@ mindmap
Classification and monitoring of incoming issues
```
<!-- ## Join the development -->
## Join the development
Detailed information about contributing can be found in the [contribution guide](../contributing/contributing.md).
<!-- ## Help with testing -->
<!-- ## Manage tasks -->
## Where do I start?
```tip
Detailed information about contributing can be found in the [contribution guide](../contributing/contributing.md).
```
- You could confirm the bugs in [these issues](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug+%2F+Error%22+label%3A%22Status%3A+Pending%22).
- You could help write and improve the documentation! [Here's ](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Help+wanted%21%22+label%3A%22Area%3A+Documentation%22)some inspiration.
- You could start getting some knowledge of the code base by working on [these "good first issues"](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22+).

102
packages/mermaid/src/docs/community/setup.md
View File

@ -1,8 +1,4 @@
# Initial setup
> The following documentation describes how to work with Mermaid in your host environment.
> There's also a [Docker installation guide](../community/docker-setup.md)
> if you prefer to work in a Docker environment.
# Initial Setup
Initial setup consists of 3 main steps:
@ -10,12 +6,39 @@ Initial setup consists of 3 main steps:
flowchart LR
source --> requirements --> setup
source[Get the source code]
requirements[Install the requirements]
setup[Setup and launch]
source[Get the source code]
setup[Install packages]
```
## Choose Your Environment
We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences.
## Install Requirements
### 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.
## Get the Source Code
In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests.
@ -26,24 +49,9 @@ Then you **clone** a copy to your local development machine (e.g. where you code
[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
## Technical Requirements
> The following documentation describes how to work with Mermaid in your host environment.
> There's also a [Docker installation guide](../community/docker-setup.md)
> if you prefer to work in a Docker environment.
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)
Follow the setup steps below to start the development.
## Setup and Launch
### Switch to project
```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)
@ -51,44 +59,54 @@ Once you have cloned the repository onto your development machine, change into t
cd mermaid
```
### Install packages
## Setup
Run `npx pnpm install`. You will need `npx` for this because volta doesn't support it yet.
### 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
```
### Launch Mermaid
### 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
npx pnpm run dev
chmod +x run
```
Now you are ready to make your changes! Edit whichever files in `src` as required.
```tip
To get detailed help simply type `./run` or `./run help`.
Open <http://localhost:9000> in your browser, after starting the dev server.
There is a list of demos that can be used to see and test your changes.
It also has short _Development quick start guide_ embedded.
```
If you need a specific diagram, you can duplicate the `example.html` file in `/demos/dev` and add your own mermaid code to your copy.
```bash
./run pnpm install # Install packages
```
That will be served at <http://localhost:9000/dev/your-file-name.html>.
After making code changes, the dev server will rebuild the mermaid library. You will need to reload the browser page yourself to see the changes. (PRs for auto reload are welcome!)
### Launch Documentaion Website
## Verify Everything is Working
## 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.)

4
packages/mermaid/src/docs/community/workflow.md
View File

@ -93,9 +93,11 @@ A bug described in issue 1123 that causes random ugly red text in multiple diagr
## Make changes
Source code along with the documentation is located in packages [`packages/mermaid`](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs) folder.
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