From 57f0a3aa8e0afe79b582dc13c10129ee181cb091 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Mon, 11 Dec 2023 05:08:42 +0300 Subject: [PATCH 01/39] Contribution documentation improvements --- .gitignore | 1 + docker-compose.yml | 4 +- packages/mermaid/scripts/docs.mts | 4 +- .../mermaid/src/docs/.vitepress/config.ts | 34 ++- packages/mermaid/src/docs/community/code.md | 13 +- ...{docker-development.md => docker-setup.md} | 30 +-- .../src/docs/community/documentation.md | 27 +-- packages/mermaid/src/docs/community/intro.md | 49 +++++ .../{newDiagram.md => new-diagram.md} | 0 .../mermaid/src/docs/community/quick-start.md | 1 + .../community/{development.md => setup.md} | 30 +-- .../mermaid/src/docs/community/workflow.md | 130 ++++++++++++ packages/mermaid/src/docs/config/advanced.md | 24 --- packages/mermaid/src/docs/contributing | 1 + .../Tutorials.md => ecosystem/tutorials.md} | 0 pnpm-lock.yaml | 196 +++++++++++++++--- 16 files changed, 425 insertions(+), 119 deletions(-) rename packages/mermaid/src/docs/community/{docker-development.md => docker-setup.md} (75%) create mode 100644 packages/mermaid/src/docs/community/intro.md rename packages/mermaid/src/docs/community/{newDiagram.md => new-diagram.md} (100%) create mode 100644 packages/mermaid/src/docs/community/quick-start.md rename packages/mermaid/src/docs/community/{development.md => setup.md} (78%) create mode 100644 packages/mermaid/src/docs/community/workflow.md delete mode 100644 packages/mermaid/src/docs/config/advanced.md create mode 120000 packages/mermaid/src/docs/contributing rename packages/mermaid/src/docs/{config/Tutorials.md => ecosystem/tutorials.md} (100%) diff --git a/.gitignore b/.gitignore index 6a1cc85e51..e6728b03f7 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,4 @@ stats/ demos/dev/** !/demos/dev/example.html +tsx-0/** diff --git a/docker-compose.yml b/docker-compose.yml index e2484bdc52..a48cf5b8a2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,9 +5,9 @@ services: stdin_open: true tty: true working_dir: /mermaid - mem_limit: '4G' + mem_limit: '6G' environment: - - NODE_OPTIONS=--max_old_space_size=4096 + - NODE_OPTIONS=--max_old_space_size=6096 volumes: - ./:/mermaid - root_cache:/root/.cache diff --git a/packages/mermaid/scripts/docs.mts b/packages/mermaid/scripts/docs.mts index 3689cb68ba..42e299c54f 100644 --- a/packages/mermaid/scripts/docs.mts +++ b/packages/mermaid/scripts/docs.mts @@ -60,13 +60,11 @@ const CDN_URL = 'https://cdn.jsdelivr.net/npm'; // 'https://unpkg.com'; const MERMAID_KEYWORD = 'mermaid'; const MERMAID_CODE_ONLY_KEYWORD = 'mermaid-example'; +const MERMAID_DIAGRAM_ONLY = 'mermaid-nocode'; // These keywords will produce both a mermaid diagram and a code block with the diagram source const MERMAID_EXAMPLE_KEYWORDS = [MERMAID_KEYWORD, 'mmd', MERMAID_CODE_ONLY_KEYWORD]; // 'mmd' is an old keyword that used to be used -// This keyword will only produce a mermaid diagram -const MERMAID_DIAGRAM_ONLY = 'mermaid-nocode'; - // These will be transformed into block quotes const BLOCK_QUOTE_KEYWORDS = ['note', 'tip', 'warning', 'danger']; diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index 8601664fa5..db1fdfef07 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -71,8 +71,8 @@ function nav() { { text: 'Docs', link: '/intro/', activeMatch: '/intro/' }, { text: 'Tutorials', - link: '/config/Tutorials', - activeMatch: '/config/', + link: '/ecosystem/tutorials', + activeMatch: '/ecosystem/', }, { text: 'Integrations', @@ -81,8 +81,8 @@ function nav() { }, { text: 'Contributing', - link: '/community/development.html', - activeMatch: '/community/', + link: '/contributing/intro', + activeMatch: '/contributing/', }, { text: 'Latest News', @@ -95,11 +95,7 @@ function nav() { { text: 'Changelog', link: 'https://github.com/mermaid-js/mermaid/releases', - }, - { - text: 'Contributing', - link: '/community/development', - }, + } ], }, { @@ -167,7 +163,6 @@ function sidebarConfig() { collapsed: false, items: [ { text: 'Configuration', link: '/config/configuration' }, - { text: 'Tutorials', link: '/config/Tutorials' }, { text: 'API-Usage', link: '/config/usage' }, { text: 'Mermaid API Configuration', link: '/config/setup/README' }, { text: 'Mermaid Configuration Options', link: '/config/schema-docs/config' }, @@ -175,7 +170,6 @@ function sidebarConfig() { { text: 'Theming', link: '/config/theming' }, { text: 'Accessibility', link: '/config/accessibility' }, { text: 'Mermaid CLI', link: '/config/mermaidCLI' }, - { text: 'Advanced usage', link: '/config/advanced' }, { text: 'FAQ', link: '/config/faq' }, ], }, @@ -189,6 +183,7 @@ function sidebarEcosystem() { collapsed: false, items: [ { text: 'Mermaid Chart', link: '/ecosystem/mermaid-chart' }, + { text: 'Tutorials', link: '/ecosystem/tutorials' }, { text: 'Integrations - Community', link: '/ecosystem/integrations-community' }, { text: 'Integrations - Create', link: '/ecosystem/integrations-create' }, ], @@ -199,15 +194,18 @@ function sidebarEcosystem() { function sidebarCommunity() { return [ { - text: '🙌 Contributions and Community', + text: '🙌 Contributing', collapsed: false, items: [ - { text: 'Contributing to Mermaid', link: '/community/development' }, - { text: 'Contributing Code', link: '/community/code' }, - { text: 'Contributing Documentation', link: '/community/documentation' }, - { text: 'Questions and Suggestions', link: '/community/questions-and-suggestions' }, - { text: 'Adding Diagrams', link: '/community/newDiagram' }, - { text: 'Security', link: '/community/security' }, + { text: 'Contributing to Mermaid', link: '/contributing/intro' }, + { text: 'Quick start guide', link: '/contributing/quick-start' }, + { text: 'Initial setup', link: '/contributing/setup' }, + { text: 'Workflow', link: '/contributing/workflow' }, + { text: 'Code', link: '/contributing/code' }, + { text: 'Documentation', link: '/contributing/documentation' }, + { text: 'Questions and Suggestions', link: '/contributing/questions-and-suggestions' }, + { text: 'Adding Diagrams', link: '/contributing/new-diagram' }, + { text: 'Security', link: '/contributing/security' }, ], }, ]; diff --git a/packages/mermaid/src/docs/community/code.md b/packages/mermaid/src/docs/community/code.md index 93a5fcd953..b1f225d50b 100644 --- a/packages/mermaid/src/docs/community/code.md +++ b/packages/mermaid/src/docs/community/code.md @@ -4,7 +4,13 @@ The basic steps for contributing code are: ```mermaid graph LR - 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] + git --> codeTest --> doc --> submit --> review + + 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] ``` 1. **Create** and checkout a git branch and work on your code in the branch @@ -47,12 +53,17 @@ You can always check current [configuration of labelling and branch prefixes](ht 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. +```tip **Ex: 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 **Ex: A bug described in issue 1123 that causes random ugly red text in multiple diagram types** + `bug/1123_fix_random_ugly_red_text` +``` ## 2. Write Tests diff --git a/packages/mermaid/src/docs/community/docker-development.md b/packages/mermaid/src/docs/community/docker-setup.md similarity index 75% rename from packages/mermaid/src/docs/community/docker-development.md rename to packages/mermaid/src/docs/community/docker-setup.md index 89e08b3f70..753c1d4b9d 100644 --- a/packages/mermaid/src/docs/community/docker-development.md +++ b/packages/mermaid/src/docs/community/docker-setup.md @@ -1,14 +1,20 @@ -# Contributing to Mermaid via Docker +# 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/development.md) +> There's also a [host installation guide](../community/setup.md) > if you prefer to work without a Docker environment. -So you want to help? That's great! +Initial setup consists of 3 main steps:: -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) +```mermaid-nocode +flowchart LR + source --> requirements --> setup + + source[Get the source code] + requirements[Install the requirements] + setup[Setup and launch] -Here are a few things to get you started on the right path. +``` ## Get the Source Code @@ -23,7 +29,7 @@ Then you **clone** a copy to your local development machine (e.g. where you code ## Technical Requirements > The following documentation describes how to work with Mermaid in a Docker environment. -> There's also a [host installation guide](../community/development.md) +> 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. @@ -87,18 +93,16 @@ After making code changes, the dev server will rebuild the mermaid library. You ## 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 -./run pnpm test +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.) -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index 6a0df983d1..2c33af410c 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -1,21 +1,18 @@ # Contributing Documentation -**_[TODO: This section is still a WIP. It still needs MAJOR revision.]_** - 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 docs are located in the `packages/mermaid/src/docs` folder and are written in Markdown. Just pick the right section and start typing. +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. +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 to Documentation -We are a little less strict here, it is OK to commit directly in the `develop` branch if you are a collaborator. - -The documentation is located in the `packages/mermaid/src/docs` directory and organized according to relevant subfolder. +```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. +``` ```mermaid flowchart LR @@ -25,6 +22,12 @@ flowchart LR ``` +It is OK to commit directly in the `develop` branch if you are a collaborator. + +```tip +If the change is **only** to the documentation, you can get your changes published to the site quicker by making a PR to the `master` branch. In that case, your branch should be based on master, not develop. +``` + 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. @@ -46,14 +49,6 @@ Danger content ``` ```` -```note -If the change is _only_ to the documentation, you can get your changes published to the site quicker by making a PR to the `master` branch. In that case, your branch should be based on master, not develop. -``` - -We encourage contributions to the documentation at [packages/mermaid/src/docs in the _develop_ branch](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs). - -**_DO NOT CHANGE FILES IN `/docs`_** - ## The official documentation site **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md new file mode 100644 index 0000000000..953f98e671 --- /dev/null +++ b/packages/mermaid/src/docs/community/intro.md @@ -0,0 +1,49 @@ +# Contributing to Mermaid + +So you want to help? That's great! + +![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) + +Here are a few things to get you started on the right path. + +## How can I help? + +```mermaid-nocode +mindmap + root)Contribution( + Development + Solving issues + Adding new diagrams + Handling pull requests + Updating tooling + Testing + Verification of fixed issues + Regression testing in connection with releases + Testing pull requests + Management + Coordinating the work + Classification and monitoring of incoming issues +``` + +## Join the development + +[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) + +## Where do I start? + +* 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+). +* You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! +* You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! + +Detailed information about contributing can be found in the [contribution guide](https://github.com/mermaid-js/mermaid/blob/master/CONTRIBUTING.md). + + +## Last Words + +Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. + +[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) + +![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/packages/mermaid/src/docs/community/newDiagram.md b/packages/mermaid/src/docs/community/new-diagram.md similarity index 100% rename from packages/mermaid/src/docs/community/newDiagram.md rename to packages/mermaid/src/docs/community/new-diagram.md diff --git a/packages/mermaid/src/docs/community/quick-start.md b/packages/mermaid/src/docs/community/quick-start.md new file mode 100644 index 0000000000..84ae492eaa --- /dev/null +++ b/packages/mermaid/src/docs/community/quick-start.md @@ -0,0 +1 @@ +quick start contributing guide \ No newline at end of file diff --git a/packages/mermaid/src/docs/community/development.md b/packages/mermaid/src/docs/community/setup.md similarity index 78% rename from packages/mermaid/src/docs/community/development.md rename to packages/mermaid/src/docs/community/setup.md index fc11a1f6c0..2545d315a8 100644 --- a/packages/mermaid/src/docs/community/development.md +++ b/packages/mermaid/src/docs/community/setup.md @@ -1,12 +1,20 @@ -# Contributing to Mermaid +# Initial setup > The following documentation describes how to work with Mermaid in your host environment. -> There's also a [Docker installation guide](../community/docker-development.md) +> There's also a [Docker installation guide](../community/docker-setup.md) > if you prefer to work in a Docker environment. -So you want to help? That's great! +Initial setup consists of 3 main steps: -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) +```mermaid-nocode +flowchart LR + source --> requirements --> setup + + source[Get the source code] + requirements[Install the requirements] + setup[Setup and launch] + +``` Here are a few things to get you started on the right path. @@ -18,12 +26,12 @@ Then you **clone** a copy to your local development machine (e.g. where you code [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) +[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-development.md) +> 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: @@ -71,6 +79,8 @@ After making code changes, the dev server will rebuild the mermaid library. You ## 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 @@ -80,11 +90,3 @@ 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.) - -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md new file mode 100644 index 0000000000..313fd10787 --- /dev/null +++ b/packages/mermaid/src/docs/community/workflow.md @@ -0,0 +1,130 @@ +# 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. + +The basic steps to start contributing code and documentation are: + +```mermaid-nocode + flowchart TB + + fetch --> branch --> update --> submit --> review --> fetch + fetch[Fetch development branch] + branch[Checkout a new branch] + update[Make changes] + submit[Submit a PR] + review[Review and merge] +``` + +## Fech latest code + +```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` +``` + +## Checkout new branch + +Create a new branch for your work: + +```bash +git checkout develop # make sure you are on development branch +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-nocode +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 along with the documentation is located in packages [`packages/mermaid`](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs) folder. +You may need to update both, depending on your task. + +## 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: + +``` +Resolves # +``` +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. diff --git a/packages/mermaid/src/docs/config/advanced.md b/packages/mermaid/src/docs/config/advanced.md deleted file mode 100644 index 4ab4774285..0000000000 --- a/packages/mermaid/src/docs/config/advanced.md +++ /dev/null @@ -1,24 +0,0 @@ -# Advanced mermaid (Coming soon..) - -## splitting mermaid code from html - -A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so: - -```html -... - - - -``` - -The actual mermaid file could for example look like this: - -```javascript -mermaid content ... -``` - -## mermaid configuration options - -```markdown -(coming soon) -``` diff --git a/packages/mermaid/src/docs/contributing b/packages/mermaid/src/docs/contributing new file mode 120000 index 0000000000..013cf3ce01 --- /dev/null +++ b/packages/mermaid/src/docs/contributing @@ -0,0 +1 @@ +community/ \ No newline at end of file diff --git a/packages/mermaid/src/docs/config/Tutorials.md b/packages/mermaid/src/docs/ecosystem/tutorials.md similarity index 100% rename from packages/mermaid/src/docs/config/Tutorials.md rename to packages/mermaid/src/docs/ecosystem/tutorials.md diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1a872627cc..0df111ebd8 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -481,6 +481,61 @@ importers: specifier: ^7.0.0 version: 7.0.0 + packages/mermaid/src/vitepress: + dependencies: + '@vueuse/core': + specifier: ^10.1.0 + version: 10.1.0(vue@3.3.4) + jiti: + specifier: ^1.18.2 + version: 1.18.2 + mermaid: + specifier: workspace:^ + version: link:../.. + vue: + specifier: ^3.3 + version: 3.3.4 + devDependencies: + '@iconify-json/carbon': + specifier: ^1.1.16 + version: 1.1.16 + '@unocss/reset': + specifier: ^0.58.0 + version: 0.58.0 + '@vite-pwa/vitepress': + specifier: ^0.3.0 + version: 0.3.0(vite-plugin-pwa@0.17.0) + '@vitejs/plugin-vue': + specifier: ^4.2.1 + version: 4.2.1(vite@4.4.12)(vue@3.3.4) + fast-glob: + specifier: ^3.2.12 + version: 3.2.12 + https-localhost: + specifier: ^4.7.1 + version: 4.7.1 + pathe: + specifier: ^1.1.0 + version: 1.1.0 + unocss: + specifier: ^0.58.0 + version: 0.58.0(postcss@8.4.31)(rollup@2.79.1)(vite@4.4.12) + unplugin-vue-components: + specifier: ^0.26.0 + version: 0.26.0(rollup@2.79.1)(vue@3.3.4) + vite: + specifier: ^4.4.12 + version: 4.4.12(@types/node@18.17.5) + vite-plugin-pwa: + specifier: ^0.17.0 + version: 0.17.0(vite@4.4.12)(workbox-build@7.0.0)(workbox-window@7.0.0) + vitepress: + specifier: 1.0.0-rc.31 + version: 1.0.0-rc.31(@algolia/client-search@4.19.1)(@types/node@18.17.5)(postcss@8.4.31)(search-insights@2.7.0)(typescript@5.1.6) + workbox-window: + specifier: ^7.0.0 + version: 7.0.0 + tests/webpack: dependencies: '@mermaid-js/mermaid-example-diagram': @@ -1372,7 +1427,6 @@ packages: /@babel/helper-string-parser@7.23.4: resolution: {integrity: sha512-803gmbQdqwdf4olxrX4AJyFBV/RTr3rSmOj0rKwesmzlfhYNDEs+/iOcznzpNWlJlIlTJC2QfPFcHB6DlzdVLQ==} engines: {node: '>=6.9.0'} - dev: true /@babel/helper-validator-identifier@7.22.20: resolution: {integrity: sha512-Y4OZ+ytlatR8AI+8KZfKuL5urKp7qey08ha31L8b3BwewJAoJamTzyvxPR/5D+KkdJCGPq/+8TukHBlY10FX9A==} @@ -1455,7 +1509,6 @@ packages: hasBin: true dependencies: '@babel/types': 7.23.5 - dev: true /@babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression@7.22.5(@babel/core@7.23.5): resolution: {integrity: sha512-NP1M5Rf+u2Gw9qfSO4ihjcTGW5zXTi36ITLd4/EoAcEhIZ0yjMqmftDNl3QC19CX7olhrjpyU454g/2W7X0jvQ==} @@ -2547,7 +2600,6 @@ packages: '@babel/helper-string-parser': 7.23.4 '@babel/helper-validator-identifier': 7.22.20 to-fast-properties: 2.0.0 - dev: true /@bcherny/json-schema-ref-parser@9.0.9: resolution: {integrity: sha512-vmEmnJCfpkLdas++9OYg6riIezTYqTHpqUTODJzHLzs5UnXujbOJW9VwcVCnyo1mVRt32FRr23iXBx/sX8YbeQ==} @@ -4397,21 +4449,6 @@ packages: picomatch: 2.3.1 dev: true - /@rollup/pluginutils@5.0.5(rollup@2.79.1): - resolution: {integrity: sha512-6aEYR910NyP73oHiJglti74iRyOwgFU4x3meH/H8OJx6Ry0j6cOVZ5X/wTvub7G7Ao6qaHBEaNsV3GLJkSsF+Q==} - engines: {node: '>=14.0.0'} - peerDependencies: - rollup: ^1.20.0||^2.0.0||^3.0.0||^4.0.0 - peerDependenciesMeta: - rollup: - optional: true - dependencies: - '@types/estree': 1.0.1 - estree-walker: 2.0.2 - picomatch: 2.3.1 - rollup: 2.79.1 - dev: true - /@rollup/pluginutils@5.1.0(rollup@2.79.1): resolution: {integrity: sha512-XTIWOPPcpvyKI6L1NHo0lFlCyznUEyPmPY1mc3KpPVDYulHSTvyeLNVW00QTLIAFNhR3kYnJTQHeGqU4M3n09g==} engines: {node: '>=14.0.0'} @@ -4598,7 +4635,7 @@ packages: /@types/babel__core@7.20.1: resolution: {integrity: sha512-aACu/U/omhdk15O4Nfb+fHgH/z3QsfQzpnvRZhYhThms83ZnAOZz7zZAWO7mn2yyNQaA4xTO8GLK3uqFU4bYYw==} dependencies: - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@babel/types': 7.23.0 '@types/babel__generator': 7.6.4 '@types/babel__template': 7.4.1 @@ -4614,7 +4651,7 @@ packages: /@types/babel__template@7.4.1: resolution: {integrity: sha512-azBFKemX6kMg5Io+/rdGT0dkGreboUVR0Cdm3fz9QJWpaQGJRQXl7C+6hOTCZcMll7KFyEQpgbYI2lHdsS4U7g==} dependencies: - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@babel/types': 7.23.0 dev: true @@ -5558,6 +5595,22 @@ packages: resolution: {integrity: sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==} dev: true + /@unocss/astro@0.58.0(rollup@2.79.1)(vite@4.4.12): + resolution: {integrity: sha512-df+tEFO5eKXjQOwSWQhS9IdjD0sfLHLtn8U09sEKR2Nmh5CvpwyBxmvLQgOCilPou7ehmyKfsyGRLZg7IMp+Ew==} + peerDependencies: + vite: ^2.9.0 || ^3.0.0-0 || ^4.0.0 || ^5.0.0-0 + peerDependenciesMeta: + vite: + optional: true + dependencies: + '@unocss/core': 0.58.0 + '@unocss/reset': 0.58.0 + '@unocss/vite': 0.58.0(rollup@2.79.1)(vite@4.4.12) + vite: 4.4.12(@types/node@18.17.5) + transitivePeerDependencies: + - rollup + dev: true + /@unocss/astro@0.58.0(rollup@2.79.1)(vite@4.5.0): resolution: {integrity: sha512-df+tEFO5eKXjQOwSWQhS9IdjD0sfLHLtn8U09sEKR2Nmh5CvpwyBxmvLQgOCilPou7ehmyKfsyGRLZg7IMp+Ew==} peerDependencies: @@ -5752,6 +5805,26 @@ packages: '@unocss/core': 0.58.0 dev: true + /@unocss/vite@0.58.0(rollup@2.79.1)(vite@4.4.12): + resolution: {integrity: sha512-OCUOLMSOBEtXOEyBbAvMI3/xdR175BWRzmvV9Wc34ANZclEvCdVH8+WU725ibjY4VT0gVIuX68b13fhXdHV41A==} + peerDependencies: + vite: ^2.9.0 || ^3.0.0-0 || ^4.0.0 || ^5.0.0-0 + dependencies: + '@ampproject/remapping': 2.2.1 + '@rollup/pluginutils': 5.1.0(rollup@2.79.1) + '@unocss/config': 0.58.0 + '@unocss/core': 0.58.0 + '@unocss/inspector': 0.58.0 + '@unocss/scope': 0.58.0 + '@unocss/transformer-directives': 0.58.0 + chokidar: 3.5.3 + fast-glob: 3.3.2 + magic-string: 0.30.5 + vite: 4.4.12(@types/node@18.17.5) + transitivePeerDependencies: + - rollup + dev: true + /@unocss/vite@0.58.0(rollup@2.79.1)(vite@4.5.0): resolution: {integrity: sha512-OCUOLMSOBEtXOEyBbAvMI3/xdR175BWRzmvV9Wc34ANZclEvCdVH8+WU725ibjY4VT0gVIuX68b13fhXdHV41A==} peerDependencies: @@ -5777,7 +5850,18 @@ packages: peerDependencies: vite-plugin-pwa: '>=0.17.0 <1' dependencies: - vite-plugin-pwa: 0.17.0(vite@4.5.0)(workbox-build@7.0.0)(workbox-window@7.0.0) + vite-plugin-pwa: 0.17.0(vite@4.4.12)(workbox-build@7.0.0)(workbox-window@7.0.0) + dev: true + + /@vitejs/plugin-vue@4.2.1(vite@4.4.12)(vue@3.3.4): + resolution: {integrity: sha512-ZTZjzo7bmxTRTkb8GSTwkPOYDIP7pwuyV+RV53c9PYUouwcbkIZIvWvNWlX2b1dYZqtOv7D6iUAnJLVNGcLrSw==} + engines: {node: ^14.18.0 || >=16.0.0} + peerDependencies: + vite: ^4.0.0 + vue: ^3.2.25 + dependencies: + vite: 4.4.12(@types/node@18.17.5) + vue: 3.3.4 dev: true /@vitejs/plugin-vue@4.2.1(vite@4.5.0)(vue@3.3.4): @@ -5909,7 +5993,7 @@ packages: /@vue/compiler-core@3.3.8: resolution: {integrity: sha512-hN/NNBUECw8SusQvDSqqcVv6gWq8L6iAktUR0UF3vGu2OhzRqcOiAno0FmBJWwxhYEXRlQJT5XnoKsVq1WZx4g==} dependencies: - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@vue/shared': 3.3.8 estree-walker: 2.0.2 source-map-js: 1.0.2 @@ -5945,7 +6029,7 @@ packages: /@vue/compiler-sfc@3.3.8: resolution: {integrity: sha512-WMzbUrlTjfYF8joyT84HfwwXo+8WPALuPxhy+BZ6R4Aafls+jDBnSz8PDz60uFhuqFbl3HxRfxvDzrUf3THwpA==} dependencies: - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@vue/compiler-core': 3.3.8 '@vue/compiler-dom': 3.3.8 '@vue/compiler-ssr': 3.3.8 @@ -5980,7 +6064,7 @@ packages: /@vue/reactivity-transform@3.3.4: resolution: {integrity: sha512-MXgwjako4nu5WFLAjpBnCj/ieqcjE2aJBINUNQzkZQfzIZA4xn+0fV1tIYBJvvva3N3OvKGofRLvQIwEQPpaXw==} dependencies: - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@vue/compiler-core': 3.3.4 '@vue/shared': 3.3.4 estree-walker: 2.0.2 @@ -5989,7 +6073,7 @@ packages: /@vue/reactivity-transform@3.3.8: resolution: {integrity: sha512-49CvBzmZNtcHua0XJ7GdGifM8GOXoUMOX4dD40Y5DxI3R8OUhMlvf2nvgUAcPxaXiV5MQQ1Nwy09ADpnLQUqRw==} dependencies: - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@vue/compiler-core': 3.3.8 '@vue/shared': 3.3.8 estree-walker: 2.0.2 @@ -6067,7 +6151,7 @@ packages: '@types/web-bluetooth': 0.0.16 '@vueuse/metadata': 10.1.0 '@vueuse/shared': 10.1.0(vue@3.3.4) - vue-demi: 0.14.5(vue@3.3.4) + vue-demi: 0.14.6(vue@3.3.4) transitivePeerDependencies: - '@vue/composition-api' - vue @@ -16295,6 +16379,45 @@ packages: engines: {node: '>= 10.0.0'} dev: true + /unocss@0.58.0(postcss@8.4.31)(rollup@2.79.1)(vite@4.4.12): + resolution: {integrity: sha512-MSPRHxBqWN+1AHGV+J5uUy4//e6ZBK6O+ISzD0qrXcCD/GNtxk1+lYjOK2ltkUiKX539+/KF91vNxzhhwEf+xA==} + engines: {node: '>=14'} + peerDependencies: + '@unocss/webpack': 0.58.0 + vite: ^2.9.0 || ^3.0.0-0 || ^4.0.0 || ^5.0.0-0 + peerDependenciesMeta: + '@unocss/webpack': + optional: true + vite: + optional: true + dependencies: + '@unocss/astro': 0.58.0(rollup@2.79.1)(vite@4.4.12) + '@unocss/cli': 0.58.0(rollup@2.79.1) + '@unocss/core': 0.58.0 + '@unocss/extractor-arbitrary-variants': 0.58.0 + '@unocss/postcss': 0.58.0(postcss@8.4.31) + '@unocss/preset-attributify': 0.58.0 + '@unocss/preset-icons': 0.58.0 + '@unocss/preset-mini': 0.58.0 + '@unocss/preset-tagify': 0.58.0 + '@unocss/preset-typography': 0.58.0 + '@unocss/preset-uno': 0.58.0 + '@unocss/preset-web-fonts': 0.58.0 + '@unocss/preset-wind': 0.58.0 + '@unocss/reset': 0.58.0 + '@unocss/transformer-attributify-jsx': 0.58.0 + '@unocss/transformer-attributify-jsx-babel': 0.58.0 + '@unocss/transformer-compile-class': 0.58.0 + '@unocss/transformer-directives': 0.58.0 + '@unocss/transformer-variant-group': 0.58.0 + '@unocss/vite': 0.58.0(rollup@2.79.1)(vite@4.4.12) + vite: 4.4.12(@types/node@18.17.5) + transitivePeerDependencies: + - postcss + - rollup + - supports-color + dev: true + /unocss@0.58.0(postcss@8.4.31)(rollup@2.79.1)(vite@4.5.0): resolution: {integrity: sha512-MSPRHxBqWN+1AHGV+J5uUy4//e6ZBK6O+ISzD0qrXcCD/GNtxk1+lYjOK2ltkUiKX539+/KF91vNxzhhwEf+xA==} engines: {node: '>=14'} @@ -16353,7 +16476,7 @@ packages: optional: true dependencies: '@antfu/utils': 0.7.6 - '@rollup/pluginutils': 5.0.5(rollup@2.79.1) + '@rollup/pluginutils': 5.1.0(rollup@2.79.1) chokidar: 3.5.3 debug: 4.3.4(supports-color@8.1.1) fast-glob: 3.3.2 @@ -16546,6 +16669,24 @@ packages: - supports-color dev: true + /vite-plugin-pwa@0.17.0(vite@4.4.12)(workbox-build@7.0.0)(workbox-window@7.0.0): + resolution: {integrity: sha512-cOyEG8EEc7JHmyMapTnjK2j0g2BIC3ErlmOHyGzVu8hqjyF9Jt6yWMmVNFtpA6v/NNyzP28ARf3vwzIAzR1kaw==} + engines: {node: '>=16.0.0'} + peerDependencies: + vite: ^3.1.0 || ^4.0.0 || ^5.0.0 + workbox-build: ^7.0.0 + workbox-window: ^7.0.0 + dependencies: + debug: 4.3.4(supports-color@8.1.1) + fast-glob: 3.3.2 + pretty-bytes: 6.1.1 + vite: 4.4.12(@types/node@18.17.5) + workbox-build: 7.0.0 + workbox-window: 7.0.0 + transitivePeerDependencies: + - supports-color + dev: true + /vite-plugin-pwa@0.17.0(vite@4.5.0)(workbox-build@7.0.0)(workbox-window@7.0.0): resolution: {integrity: sha512-cOyEG8EEc7JHmyMapTnjK2j0g2BIC3ErlmOHyGzVu8hqjyF9Jt6yWMmVNFtpA6v/NNyzP28ARf3vwzIAzR1kaw==} engines: {node: '>=16.0.0'} @@ -16905,7 +17046,6 @@ packages: optional: true dependencies: vue: 3.3.4 - dev: true /vue-demi@0.14.6(vue@3.3.8): resolution: {integrity: sha512-8QA7wrYSHKaYgUxDA5ZC24w+eHm3sYCbp0EzcDwKqN3p6HqtTCGR/GVsPyZW92unff4UlcSh++lmqDWN3ZIq4w==} From 01908b127897336dd81f037108795dda52d107a5 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Mon, 11 Dec 2023 05:22:58 +0300 Subject: [PATCH 02/39] Development Into planning --- packages/mermaid/src/docs/community/intro.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 953f98e671..633282b145 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -29,6 +29,10 @@ mindmap [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +## Help with testing + +## Manage tasks + ## Where do I start? * 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). From 0506ba872a54e1490af3372af91dff8c245c69c9 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Sun, 17 Dec 2023 13:35:49 +0300 Subject: [PATCH 03/39] Fixed linters --- packages/mermaid/src/docs/community/docker-setup.md | 4 +--- packages/mermaid/src/docs/community/intro.md | 11 +++++------ packages/mermaid/src/docs/community/setup.md | 2 +- packages/mermaid/src/docs/community/workflow.md | 6 +++--- 4 files changed, 10 insertions(+), 13 deletions(-) diff --git a/packages/mermaid/src/docs/community/docker-setup.md b/packages/mermaid/src/docs/community/docker-setup.md index 753c1d4b9d..6e6d421ca9 100644 --- a/packages/mermaid/src/docs/community/docker-setup.md +++ b/packages/mermaid/src/docs/community/docker-setup.md @@ -9,7 +9,7 @@ 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] @@ -104,5 +104,3 @@ 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.) - - diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 633282b145..3d618d1531 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -35,15 +35,14 @@ mindmap ## Where do I start? -* 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+). -* You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! -* You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! +- 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+). +- You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! +- You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! Detailed information about contributing can be found in the [contribution guide](https://github.com/mermaid-js/mermaid/blob/master/CONTRIBUTING.md). - ## Last Words Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. diff --git a/packages/mermaid/src/docs/community/setup.md b/packages/mermaid/src/docs/community/setup.md index 2545d315a8..ac087ad9e5 100644 --- a/packages/mermaid/src/docs/community/setup.md +++ b/packages/mermaid/src/docs/community/setup.md @@ -9,7 +9,7 @@ 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] diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md index 313fd10787..ad19789538 100644 --- a/packages/mermaid/src/docs/community/workflow.md +++ b/packages/mermaid/src/docs/community/workflow.md @@ -69,15 +69,14 @@ flowchart LR 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 @@ -116,6 +115,7 @@ In case in its description contains a [magic comment](https://docs.github.com/en ``` Resolves # ``` + You can edit it if needed. ## Congratulations From f66f4f438f445bc130e248598616d483c6892109 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Tue, 19 Dec 2023 00:54:33 +0300 Subject: [PATCH 04/39] Use deep outline for the whole documentation website --- .../mermaid/src/docs/.vitepress/config.ts | 5 +++- .../src/docs/community/documentation.md | 29 +++++++++---------- packages/mermaid/src/docs/community/intro.md | 18 ++++++------ .../mermaid/src/docs/community/quick-start.md | 1 - packages/mermaid/src/docs/community/setup.md | 10 ++++--- .../docs/ecosystem/integrations-community.md | 4 --- .../src/docs/ecosystem/integrations-create.md | 4 --- .../src/docs/ecosystem/mermaid-chart.md | 4 --- packages/mermaid/src/docs/syntax/flowchart.md | 1 - 9 files changed, 33 insertions(+), 43 deletions(-) delete mode 100644 packages/mermaid/src/docs/community/quick-start.md diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index db1fdfef07..a1e7b05f83 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -49,6 +49,9 @@ export default defineConfig({ sidebar: { '/': sidebarAll(), }, + outline: { + level: 'deep', + }, socialLinks: [ { icon: 'github', link: 'https://github.com/mermaid-js/mermaid' }, { @@ -198,7 +201,7 @@ function sidebarCommunity() { collapsed: false, items: [ { text: 'Contributing to Mermaid', link: '/contributing/intro' }, - { text: 'Quick start guide', link: '/contributing/quick-start' }, + { text: 'Contributing guide', link: '/contributing/contributing' }, { text: 'Initial setup', link: '/contributing/setup' }, { text: 'Workflow', link: '/contributing/workflow' }, { text: 'Code', link: '/contributing/code' }, diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index 2c33af410c..cb5d038985 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -1,4 +1,5 @@ -# Contributing Documentation + +# Contributing to 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? @@ -6,7 +7,7 @@ The documentation is written in Markdown. It is located in the [`packages/mermai 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 to Documentation +## How to Contribute ```warning DO NOT CHANGE FILES IN `/docs` @@ -18,15 +19,21 @@ The `docs` folder will be automatically generated when committing to `packages/m flowchart LR classDef default fill:#fff,color:black,stroke:black - source["files in /packages/mermaid/src/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"] + source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` -It is OK to commit directly in the `develop` branch if you are a collaborator. +## Runing the Documentation Website -```tip -If the change is **only** to the documentation, you can get your changes published to the site quicker by making a PR to the `master` branch. In that case, your branch should be based on master, not develop. -``` +**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** + +To run the documentation site locally: + +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. + + +### Markdown extensions 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. @@ -49,14 +56,6 @@ Danger content ``` ```` -## The official documentation site - -**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** - -To run the documentation site locally: - -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. 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). diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 3d618d1531..91a58393f6 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -10,7 +10,7 @@ Here are a few things to get you started on the right path. ```mermaid-nocode mindmap - root)Contribution( + root)Contributing( Development Solving issues Adding new diagrams @@ -25,23 +25,23 @@ mindmap Classification and monitoring of incoming issues ``` -## Join the development - -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -## 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+). - You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! - You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! +- [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) -Detailed information about contributing can be found in the [contribution guide](https://github.com/mermaid-js/mermaid/blob/master/CONTRIBUTING.md). ## Last Words diff --git a/packages/mermaid/src/docs/community/quick-start.md b/packages/mermaid/src/docs/community/quick-start.md deleted file mode 100644 index 84ae492eaa..0000000000 --- a/packages/mermaid/src/docs/community/quick-start.md +++ /dev/null @@ -1 +0,0 @@ -quick start contributing guide \ No newline at end of file diff --git a/packages/mermaid/src/docs/community/setup.md b/packages/mermaid/src/docs/community/setup.md index ac087ad9e5..7574081f3e 100644 --- a/packages/mermaid/src/docs/community/setup.md +++ b/packages/mermaid/src/docs/community/setup.md @@ -16,8 +16,6 @@ flowchart LR ``` -Here are a few things to get you started on the right path. - ## Get the Source Code In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. @@ -41,7 +39,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) -Follow the setup steps below to install them and start the development. +Follow the setup steps below to start the development. ## Setup and Launch @@ -61,7 +59,7 @@ Run `npx pnpm install`. You will need `npx` for this because volta doesn't suppo npx pnpm install # npx is required for first install ``` -### Launch +### Launch Mermaid ```bash npx pnpm run dev @@ -77,6 +75,10 @@ If you need a specific diagram, you can duplicate the `example.html` file in `/d That will be served at . 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 This step is optional, but it helps to make sure that everything in development branch was OK before you started making any changes. diff --git a/packages/mermaid/src/docs/ecosystem/integrations-community.md b/packages/mermaid/src/docs/ecosystem/integrations-community.md index 1e85102ce5..f18591376c 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-community.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-community.md @@ -1,7 +1,3 @@ ---- -outline: 'deep' # shows all h3 headings in outline in Vitepress ---- - # Integrations ## Official integration: [Mermaid Chart](./mermaid-chart.md) diff --git a/packages/mermaid/src/docs/ecosystem/integrations-create.md b/packages/mermaid/src/docs/ecosystem/integrations-create.md index 421240729c..b848a90aa0 100644 --- a/packages/mermaid/src/docs/ecosystem/integrations-create.md +++ b/packages/mermaid/src/docs/ecosystem/integrations-create.md @@ -1,7 +1,3 @@ ---- -outline: 'deep' # shows all h3 headings in outline in Vitepress ---- - # Integrations - create ## Recommendations diff --git a/packages/mermaid/src/docs/ecosystem/mermaid-chart.md b/packages/mermaid/src/docs/ecosystem/mermaid-chart.md index 7d0e90024e..f7f306b947 100644 --- a/packages/mermaid/src/docs/ecosystem/mermaid-chart.md +++ b/packages/mermaid/src/docs/ecosystem/mermaid-chart.md @@ -1,7 +1,3 @@ ---- -outline: 'deep' # shows all h3 headings in outline in Vitepress ---- - # Mermaid Chart
diff --git a/packages/mermaid/src/docs/syntax/flowchart.md b/packages/mermaid/src/docs/syntax/flowchart.md index 23306acdd7..1f4bcbc4b2 100644 --- a/packages/mermaid/src/docs/syntax/flowchart.md +++ b/packages/mermaid/src/docs/syntax/flowchart.md @@ -1,6 +1,5 @@ --- title: Flowcharts Syntax -outline: 'deep' # shows all h3 headings in outline in Vitepress --- # Flowcharts - Basic Syntax From 2f3f76fa24d71878fc87d27acb4a1e918ff336ce Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Tue, 19 Dec 2023 02:48:22 +0300 Subject: [PATCH 05/39] Contribution guidelines rework --- CONTRIBUTING.md | 79 +------------ packages/mermaid/src/docs/community/code.md | 93 +++++---------- .../src/docs/community/contributing.md | 81 +++++++++++++ .../src/docs/community/docker-setup.md | 106 ------------------ .../src/docs/community/documentation.md | 56 ++++----- packages/mermaid/src/docs/community/intro.md | 9 +- packages/mermaid/src/docs/community/setup.md | 96 +++++++++------- .../mermaid/src/docs/community/workflow.md | 4 +- 8 files changed, 201 insertions(+), 323 deletions(-) mode change 100644 => 120000 CONTRIBUTING.md create mode 100644 packages/mermaid/src/docs/community/contributing.md delete mode 100644 packages/mermaid/src/docs/community/docker-setup.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 3142c57605..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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 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 . - -### 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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 120000 index 0000000000..885868c167 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +./packages/mermaid/src/docs/community/contributing.md \ No newline at end of file diff --git a/packages/mermaid/src/docs/community/code.md b/packages/mermaid/src/docs/community/code.md index b1f225d50b..129638da59 100644 --- a/packages/mermaid/src/docs/community/code.md +++ b/packages/mermaid/src/docs/community/code.md @@ -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] -``` - -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. - -## 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. +The core of Mermaid is located under `packages/mermaid/src`. -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. +## Running Mermaid Locally -**All new work should be based on the `develop` branch.** +**Host** -**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. +```bash +npx pnpm run dev +``` -We use the following naming convention for branches: +**Docker** -```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 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 . 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 . +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+)` 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.** diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md new file mode 100644 index 0000000000..f055e13198 --- /dev/null +++ b/packages/mermaid/src/docs/community/contributing.md @@ -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 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 . + +### 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) diff --git a/packages/mermaid/src/docs/community/docker-setup.md b/packages/mermaid/src/docs/community/docker-setup.md deleted file mode 100644 index 6e6d421ca9..0000000000 --- a/packages/mermaid/src/docs/community/docker-setup.md +++ /dev/null @@ -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 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 . -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.) diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index cb5d038985..3b57976359 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -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//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.** diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 91a58393f6..3783e678b5 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -25,16 +25,15 @@ mindmap Classification and monitoring of incoming issues ``` - +## Join the development + +Detailed information about contributing can be found in the [contribution guide](../contributing/contributing.md). + ## 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+). diff --git a/packages/mermaid/src/docs/community/setup.md b/packages/mermaid/src/docs/community/setup.md index 7574081f3e..8db29242c9 100644 --- a/packages/mermaid/src/docs/community/setup.md +++ b/packages/mermaid/src/docs/community/setup.md @@ -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,27 +6,18 @@ 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] ``` -## 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). +## Choose Your Environment -[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo). +We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. -## Technical Requirements +## Install 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. +### Host These are the tools we use for working with the code and documentation: @@ -39,56 +26,87 @@ 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) -Follow the setup steps below to start the development. - -## Setup and Launch +### Docker -### Switch to project +[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. -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) +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 -cd mermaid +echo $DISPLAY ``` -### Install packages +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. + +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). -Run `npx pnpm install`. You will need `npx` for this because volta doesn't support it yet. +[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo). ```bash -npx pnpm install # npx is required for first install +git clone git@github.com/your-fork/mermaid ``` -### Launch 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 +``` + +## Setup + +### Host + +Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. ```bash -npx pnpm run dev +npx pnpm install # npx is required for first install ``` -Now you are ready to make your changes! Edit whichever files in `src` as required. +### Docker -Open in your browser, after starting the dev server. -There is a list of demos that can be used to see and test your changes. +For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. -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. +Make sure that `./run` script is executable: -That will be served at . -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!) +```bash +chmod +x run +``` -### Launch Documentaion Website +```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 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.) diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md index ad19789538..c0cf1c3e61 100644 --- a/packages/mermaid/src/docs/community/workflow.md +++ b/packages/mermaid/src/docs/community/workflow.md @@ -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 From 3bc39409e5f3b0f0a2595dc4a59909f68c834230 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Tue, 19 Dec 2023 02:55:20 +0300 Subject: [PATCH 06/39] Formatting --- .github/pull_request_template.md | 2 +- docs/community/development.md | 96 --------------- docs/community/docker-development.md | 109 ------------------ docs/config/advanced.md | 30 ----- .../mermaid/src/docs/.vitepress/config.ts | 2 +- .../src/docs/community/contributing.md | 3 - .../src/docs/community/documentation.md | 2 +- packages/mermaid/src/docs/community/intro.md | 1 - 8 files changed, 3 insertions(+), 242 deletions(-) delete mode 100644 docs/community/development.md delete mode 100644 docs/community/docker-development.md delete mode 100644 docs/config/advanced.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ff34d24fd0..4934163b55 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,5 +14,5 @@ Make sure you - [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md) - [ ] :computer: have added necessary unit/e2e tests. -- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/development.md#3-update-documentation) is used for all new features. +- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/contribution/code.md#update-documentation) is used for all new features. - [ ] :bookmark: targeted `develop` branch diff --git a/docs/community/development.md b/docs/community/development.md deleted file mode 100644 index c9d8dab979..0000000000 --- a/docs/community/development.md +++ /dev/null @@ -1,96 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/development.md](../../packages/mermaid/src/docs/community/development.md). - -# Contributing to Mermaid - -> The following documentation describes how to work with Mermaid in your host environment. -> There's also a [Docker installation guide](../community/docker-development.md) -> if you prefer to work in a Docker environment. - -So you want to help? That's great! - -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) - -Here are a few things to get you started on the right path. - -## 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 your host environment. -> There's also a [Docker installation guide](../community/docker-development.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 install them and start the development. - -## 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 -``` - -### Install packages - -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 - -```bash -npx pnpm run dev -``` - -Now you are ready to make your changes! Edit whichever files in `src` as required. - -Open 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 . -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 - -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.) - -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/community/docker-development.md b/docs/community/docker-development.md deleted file mode 100644 index 9df0c8d59c..0000000000 --- a/docs/community/docker-development.md +++ /dev/null @@ -1,109 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/docker-development.md](../../packages/mermaid/src/docs/community/docker-development.md). - -# Contributing to Mermaid via Docker - -> The following documentation describes how to work with Mermaid in a Docker environment. -> There's also a [host installation guide](../community/development.md) -> if you prefer to work without a Docker environment. - -So you want to help? That's great! - -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) - -Here are a few things to get you started on the right path. - -## 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/development.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 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 . -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 - -```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.) - -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/config/advanced.md b/docs/config/advanced.md deleted file mode 100644 index 28c0ca7245..0000000000 --- a/docs/config/advanced.md +++ /dev/null @@ -1,30 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/advanced.md](../../packages/mermaid/src/docs/config/advanced.md). - -# Advanced mermaid (Coming soon..) - -## splitting mermaid code from html - -A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so: - -```html -... - - - -``` - -The actual mermaid file could for example look like this: - -```javascript -mermaid content ... -``` - -## mermaid configuration options - -```markdown -(coming soon) -``` diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index a1e7b05f83..ca5e49a1b5 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -98,7 +98,7 @@ function nav() { { text: 'Changelog', link: 'https://github.com/mermaid-js/mermaid/releases', - } + }, ], }, { diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index f055e13198..8bce7c2e9e 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -1,10 +1,7 @@ - --- - # 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 diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index 3b57976359..bd5acad120 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -14,7 +14,6 @@ It is located in the [`packages/mermaid/src/docs`](https://github.com/mermaid-js 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 @@ -33,6 +32,7 @@ Start development server for the documentation site ```bash pnpm --filter mermaid run docs:dev ``` + or ``` diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 3783e678b5..7ff1ced1e5 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -41,7 +41,6 @@ Detailed information about contributing can be found in the [contribution guide] - You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! - [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - ## Last Words Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. From 5b58883db835dfb314846405753c10cb39467d68 Mon Sep 17 00:00:00 2001 From: nirname Date: Mon, 18 Dec 2023 23:58:33 +0000 Subject: [PATCH 07/39] Update docs --- docs/community/code.md | 88 ++----- docs/community/contributing.md | 78 +++++++ docs/community/documentation.md | 77 +++---- docs/community/intro.md | 57 +++++ .../{newDiagram.md => new-diagram.md} | 2 +- docs/community/setup.md | 117 ++++++++++ docs/community/workflow.md | 132 +++++++++++ docs/contributing/code.md | 138 +++++++++++ docs/contributing/contributing.md | 78 +++++++ docs/contributing/documentation.md | 98 ++++++++ docs/contributing/img/er.png | Bin 0 -> 56576 bytes docs/contributing/intro.md | 57 +++++ docs/contributing/new-diagram.md | 217 ++++++++++++++++++ .../contributing/questions-and-suggestions.md | 25 ++ docs/contributing/security.md | 29 +++ docs/contributing/setup.md | 117 ++++++++++ docs/contributing/workflow.md | 132 +++++++++++ .../Tutorials.md => ecosystem/tutorials.md} | 2 +- 18 files changed, 1337 insertions(+), 107 deletions(-) create mode 100644 docs/community/contributing.md create mode 100644 docs/community/intro.md rename docs/community/{newDiagram.md => new-diagram.md} (98%) create mode 100644 docs/community/setup.md create mode 100644 docs/community/workflow.md create mode 100644 docs/contributing/code.md create mode 100644 docs/contributing/contributing.md create mode 100644 docs/contributing/documentation.md create mode 100644 docs/contributing/img/er.png create mode 100644 docs/contributing/intro.md create mode 100644 docs/contributing/new-diagram.md create mode 100644 docs/contributing/questions-and-suggestions.md create mode 100644 docs/contributing/security.md create mode 100644 docs/contributing/setup.md create mode 100644 docs/contributing/workflow.md rename docs/{config/Tutorials.md => ecosystem/tutorials.md} (97%) diff --git a/docs/community/code.md b/docs/community/code.md index e77a25467e..473a6da0e7 100644 --- a/docs/community/code.md +++ b/docs/community/code.md @@ -6,66 +6,42 @@ # 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-example -graph LR - 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] -``` - -```mermaid -graph LR - 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] -``` - -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. - -## 1. Checkout a git branch +## Where is the code located? -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. +The core of Mermaid is located under `packages/mermaid/src`. -Development is done in the `develop` branch. +## Running Mermaid Locally -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. +**Host** -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. +```bash +npx pnpm run dev +``` -We use the following naming convention for branches: +**Docker** -```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 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 -**Ex: A new feature described in issue 2945 that adds a new arrow type called 'florbs' to state diagrams** +Have a look at . 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. -**Ex: A bug described in issue 1123 that causes random ugly red text in multiple diagram types** -`bug/1123_fix_random_ugly_red_text` +That will be served at . +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!) -## 2. Write Tests +Edit files in `packages/mermaid/src` as required. + +## 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 +114,12 @@ 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 +131,8 @@ eg: `# Feature Name (v+)` 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.** diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 0000000000..c50f4ea05d --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,78 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/contributing.md](../../packages/mermaid/src/docs/community/contributing.md). + +# 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 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 . + +### 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) diff --git a/docs/community/documentation.md b/docs/community/documentation.md index 67d35d3958..28c7ede891 100644 --- a/docs/community/documentation.md +++ b/docs/community/documentation.md @@ -6,39 +6,60 @@ # Contributing Documentation -**_\[TODO: This section is still a WIP. It still needs MAJOR revision.]_** - 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 docs are located in the `packages/mermaid/src/docs` folder and are written in Markdown. 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. +## Where is the Documentation Located? -## How to Contribute to Documentation - -We are a little less strict here, it is OK to commit directly in the `develop` branch if you are a collaborator. +> **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. -The documentation is located in the `packages/mermaid/src/docs` directory and organized according to relevant subfolder. +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 `docs` folder will be automatically generated when committing to `packages/mermaid/src/docs` and **should not** be edited manually. +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-example flowchart LR classDef default fill:#fff,color:black,stroke:black - source["files in /packages/mermaid/src/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"] - + source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` ```mermaid flowchart LR classDef default fill:#fff,color:black,stroke:black - source["files in /packages/mermaid/src/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"] + source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] +``` + +## Running the Documentation Website Locally +**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** + +Start development server for the documentation site + +**Host** + +```bash +pnpm --filter mermaid run docs:dev ``` +or + + cd packages/mermaid + pnpm docs:dev + +**Docker** + + ./run docs:dev + +Open 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. @@ -60,26 +81,8 @@ Danger content ``` ```` -> **Note** -> If the change is _only_ to the documentation, you can get your changes published to the site quicker by making a PR to the `master` branch. In that case, your branch should be based on master, not develop. - -We encourage contributions to the documentation at [packages/mermaid/src/docs in the _develop_ branch](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/docs). - -**_DO NOT CHANGE FILES IN `/docs`_** - -## The official documentation site - -**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** - -To run the documentation site locally: - -1. Run `pnpm --filter mermaid run docs:dev` to start the dev server. (Or `pnpm docs:dev` inside the `packages/mermaid` directory.) -2. Open in your browser. - 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. @@ -88,16 +91,6 @@ _\[TODO: need to keep this in sync with [check out a git branch in Contributing 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//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.** diff --git a/docs/community/intro.md b/docs/community/intro.md new file mode 100644 index 0000000000..73392e62c6 --- /dev/null +++ b/docs/community/intro.md @@ -0,0 +1,57 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/intro.md](../../packages/mermaid/src/docs/community/intro.md). + +# Contributing to Mermaid + +So you want to help? That's great! + +![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) + +Here are a few things to get you started on the right path. + +## How can I help? + +```mermaid +mindmap + root)Contributing( + Development + Solving issues + Adding new diagrams + Handling pull requests + Updating tooling + Testing + Verification of fixed issues + Regression testing in connection with releases + Testing pull requests + Management + Coordinating the work + Classification and monitoring of incoming issues +``` + +## Join the development + +Detailed information about contributing can be found in the [contribution guide](../contributing/contributing.md). + + + + + +## Where do I start? + +- 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+). +- You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! +- You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! +- [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) + +## Last Words + +Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. + +[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) + +![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/community/newDiagram.md b/docs/community/new-diagram.md similarity index 98% rename from docs/community/newDiagram.md rename to docs/community/new-diagram.md index b90d192b27..e3febb8f58 100644 --- a/docs/community/newDiagram.md +++ b/docs/community/new-diagram.md @@ -2,7 +2,7 @@ > > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. > -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/newDiagram.md](../../packages/mermaid/src/docs/community/newDiagram.md). +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/new-diagram.md](../../packages/mermaid/src/docs/community/new-diagram.md). # Adding a New Diagram/Chart 📊 diff --git a/docs/community/setup.md b/docs/community/setup.md new file mode 100644 index 0000000000..6fd4018929 --- /dev/null +++ b/docs/community/setup.md @@ -0,0 +1,117 @@ +> **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 + + requirements[Install the requirements] + 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. + +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 +``` + +## Setup + +### 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.) diff --git a/docs/community/workflow.md b/docs/community/workflow.md new file mode 100644 index 0000000000..0f142108b9 --- /dev/null +++ b/docs/community/workflow.md @@ -0,0 +1,132 @@ +> **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. + +The basic steps to start contributing code and documentation are: + +```mermaid + flowchart TB + + fetch --> branch --> update --> submit --> review --> fetch + fetch[Fetch development branch] + branch[Checkout a new branch] + update[Make changes] + submit[Submit a PR] + review[Review and merge] +``` + +## Fech latest code + +> **💡 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` +``` + +## Checkout new branch + +Create a new branch for your work: + +```bash +git checkout develop # make sure you are on development branch +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`]\(() 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: + + Resolves # + +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. diff --git a/docs/contributing/code.md b/docs/contributing/code.md new file mode 100644 index 0000000000..435c8e6088 --- /dev/null +++ b/docs/contributing/code.md @@ -0,0 +1,138 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/code.md](../../packages/mermaid/src/docs/contributing/code.md). + +# Contributing Code + +Code it the heart of every software project. We strive to make it better. Who if not us? + +## Where is the code located? + +The core of Mermaid is located under `packages/mermaid/src`. + +## Running Mermaid Locally + +**Host** + +```bash +npx pnpm run dev +``` + +**Docker** + +```bash +./run dev +``` + +After starting the dev server open in your browser. + +Now you are ready to make your changes! + +## Make Changes + +Have a look at . 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 . +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!) + +Edit files in `packages/mermaid/src` as required. + +## 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). + +Just as important, the tests act as _specifications:_ they specify what the code does (or should do). +Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. + +If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. +(If there had been a test for the situation, the bug never would have happened in the first place.) +You may need to change existing tests if they were inaccurate. + +If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. + +### Unit Tests + +Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. + +Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) + +We use [Vitest](https://vitest.dev) to run unit tests. + +You can use the following command to run the unit tests: + +```sh +pnpm test +``` + +When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: + +```sh +pnpm test:watch +``` + +### Integration/End-to-End (e2e) tests + +These test the rendering and visual appearance of the diagrams. +This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! + +To start working with the e2e tests: + +1. Run `pnpm dev` to start the dev server +2. Start **Cypress** by running `pnpm cypress:open`. + +The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. + +When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. + +This is what a rendering test looks like: + +```js +it('should render forks and joins', () => { + imgSnapshotTest( + ` + stateDiagram + state fork_state <<fork>> + [*] --> fork_state + fork_state --> State2 + fork_state --> State3 + + state join_state <<join>> + State2 --> join_state + State3 --> join_state + join_state --> State4 + State4 --> [*] + `, + { logLevel: 0 } + ); + cy.get('svg'); +}); +``` + +**_\[TODO - running the tests against what is expected in development. ]_** +**_\[TODO - how to generate new screenshots]_** + +## 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. + +The documentation has to be updated to users know that things have changed and added! +If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. + +eg: `# Feature Name (v+)` + +We know it can sometimes be hard to code _and_ write user documentation. + +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!) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md new file mode 100644 index 0000000000..4d48765107 --- /dev/null +++ b/docs/contributing/contributing.md @@ -0,0 +1,78 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/contributing.md](../../packages/mermaid/src/docs/contributing/contributing.md). + +# 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 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 . + +### 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) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md new file mode 100644 index 0000000000..8feda27994 --- /dev/null +++ b/docs/contributing/documentation.md @@ -0,0 +1,98 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/documentation.md](../../packages/mermaid/src/docs/contributing/documentation.md). + +# 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? + +## Where is the Documentation Located? + +> **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. + +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-example +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"] +``` + +```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"] +``` + +## Running the Documentation Website Locally + +**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** + +Start development server for the documentation site + +**Host** + +```bash +pnpm --filter mermaid run docs:dev +``` + +or + + cd packages/mermaid + pnpm docs:dev + +**Docker** + + ./run docs:dev + +Open 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. + +````markdown +```note +Note content +``` + +```tip +Tip content +``` + +```warning +Warning content +``` + +```danger +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). + +_\[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. +2. Find the Markdown file (.md) to edit in the `packages/mermaid/src/docs` directory. +3. Make changes or add new documentation. +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. + +## 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.** + +The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). diff --git a/docs/contributing/img/er.png b/docs/contributing/img/er.png new file mode 100644 index 0000000000000000000000000000000000000000..21c44c257a3e0ee3e782dd5b6696602f6d9f5172 GIT binary patch literal 56576 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 **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/intro.md](../../packages/mermaid/src/docs/contributing/intro.md). + +# Contributing to Mermaid + +So you want to help? That's great! + +![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) + +Here are a few things to get you started on the right path. + +## How can I help? + +```mermaid +mindmap + root)Contributing( + Development + Solving issues + Adding new diagrams + Handling pull requests + Updating tooling + Testing + Verification of fixed issues + Regression testing in connection with releases + Testing pull requests + Management + Coordinating the work + Classification and monitoring of incoming issues +``` + +## Join the development + +Detailed information about contributing can be found in the [contribution guide](../contributing/contributing.md). + + + + + +## Where do I start? + +- 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+). +- You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! +- You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! +- [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) + +## Last Words + +Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. + +[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) + +![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/contributing/new-diagram.md b/docs/contributing/new-diagram.md new file mode 100644 index 0000000000..3f9f5f98ee --- /dev/null +++ b/docs/contributing/new-diagram.md @@ -0,0 +1,217 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/new-diagram.md](../../packages/mermaid/src/docs/contributing/new-diagram.md). + +# Adding a New Diagram/Chart 📊 + +### Step 1: Grammar & Parsing + +#### Grammar + +This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. + +For instance: + +- the flowchart starts with the keyword _graph_ +- the sequence diagram starts with the keyword _sequenceDiagram_ + +#### Store data found during parsing + +There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data. + +```jison +statement + : 'participant' actor { $$='actor'; } + | signal { $$='signal'; } + | note_statement { $$='note'; } + | 'title' message { yy.setTitle($2); } + ; +``` + +In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. + +> **Note** +> Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. + +For more info look at the example diagram type: + +The `yy` object has the following function: + +```javascript +exports.parseError = function (err, hash) { + mermaid.parseError(err, hash); +}; +``` + +when parsing the `yy` object is initialized as per below: + +```javascript +const parser = exampleParser.parser; +parser.yy = db; +``` + +### Step 2: Rendering + +Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequenceRenderer.js rather than the flowchart renderer as this is a more generic example. + +Place the renderer in the diagram folder. + +### Step 3: Detection of the new diagram type + +The second thing to do is to add the capability to detect the new diagram to type to the detectType in `diagram-api/detectType.ts`. The detection should return a key for the new diagram type. +[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type. +For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader +would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram. + +Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same. + +### Step 4: The final piece - triggering the rendering + +At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. + +## Usage of the parser as a separate module + +### Setup + +```javascript +const graph = require('./graphDb'); +const flow = require('./parser/flow'); +flow.parser.yy = graph; +``` + +### Parsing + +```javascript +flow.parser.parse(text); +``` + +### Data extraction + +```javascript +graph.getDirection(); +graph.getVertices(); +graph.getEdges(); +``` + +The parser is also exposed in the mermaid api by calling: + +```javascript +const parser = mermaid.getParser(); +``` + +Note that the parse needs a graph object to store the data as per: + +```javascript +flow.parser.yy = graph; +``` + +Look at `graphDb.js` for more details on that object. + +## Layout + +If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from. + +### Common parts of a diagram + +There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are: + +- Directives, a way of modifying the diagram configuration from within the diagram code. +- Accessibility, a way for an author to provide additional information like titles and descriptions to people accessing a text with diagrams using a screen reader. +- Themes, there is a common way to modify the styling of diagrams in Mermaid. +- Comments should follow mermaid standards + +Here are some pointers on how to handle these different areas. + +## Accessibility + +Mermaid automatically adds the following accessibility information for the diagram SVG HTML element: + +- aria-roledescription +- accessible title +- accessible description + +### aria-roledescription + +The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element. + +See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) in [the Accessible Rich Internet Applications W3 standard.](https://www.w3.org/WAI/standards-guidelines/aria/) + +### accessible title and description + +The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md) + +As a design goal, the jison syntax should be similar between the diagrams. + +```jison + +* lexical grammar */ +%lex +%x acc_title +%x acc_descr +%x acc_descr_multiline + +%% +accTitle\s*":"\s* { this.begin("acc_title");return 'acc_title'; } +(?!\n|;|#)*[^\n]* { this.popState(); return "acc_title_value"; } +accDescr\s*":"\s* { this.begin("acc_descr");return 'acc_descr'; } +(?!\n|;|#)*[^\n]* { this.popState(); return "acc_descr_value"; } +accDescr\s*"{"\s* { this.begin("acc_descr_multiline");} +[\}] { this.popState(); } +[^\}]* return "acc_descr_multiline_value"; + +statement + : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } + | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } + | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } + +``` + +The functions for setting title and description are provided by a common module. This is the import from flowDb.js: + + import { + setAccTitle, + getAccTitle, + getAccDescription, + setAccDescription, + clear as commonClear, + } from '../../commonDb'; + +The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI. + +## Theming + +Mermaid supports themes and has an integrated theming engine. You can read more about how the themes can be used [in the docs](../config/theming.md). + +When adding themes to a diagram it comes down to a few important locations in the code. + +The entry point for the styling engine is in **src/styles.js**. The getStyles function will be called by Mermaid when the styles are being applied to the diagram. + +This function will in turn call a function _your diagram should provide_ returning the css for the new diagram. The diagram specific, also which is commonly also called getStyles and located in the folder for your diagram under src/diagrams and should be named styles.js. The getStyles function will be called with the theme options as an argument like in the following example: + +```js +const getStyles = (options) => + ` + .line { + stroke-width: 1; + stroke: ${options.lineColor}; + stroke-dasharray: 2; + } + // ... + `; +``` + +Note that you need to provide your function to the main getStyles by adding it into the themes object in **src/styles.js** like in the xyzDiagram in the provided example: + +```js +const themes = { + flowchart, + 'flowchart-v2': flowchart, + sequence, + xyzDiagram, + //... +}; +``` + +The actual options and values for the colors are defined in **src/theme/theme-\[xyz].js**. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups. diff --git a/docs/contributing/questions-and-suggestions.md b/docs/contributing/questions-and-suggestions.md new file mode 100644 index 0000000000..5162886b8e --- /dev/null +++ b/docs/contributing/questions-and-suggestions.md @@ -0,0 +1,25 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/questions-and-suggestions.md](../../packages/mermaid/src/docs/contributing/questions-and-suggestions.md). + +# Questions or Suggestions? + +**_\[TODO: This section is still a WIP. It still needs MAJOR revision.]_** + +## First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. + +- [Search in Discussions](https://github.com/orgs/mermaid-js/discussions) +- [Search in Issues (Open & Closed)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue) + +If you find an open issue or discussion thread that is similar to your question but isn't answered, you can let us know that you are also interested in it. +Use the GitHub reactions to add a thumbs-up to the issue or discussion thread. + +This helps the team know the relative interest in something and helps them set priorities and assignments. + +Feel free to add to the discussion on the issue or topic. + +If you can't find anything that already addresses your question or suggestion, _open a new issue:_ + +Log in to [GitHub.com](https://www.github.com), open or append to an issue [using the GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). diff --git a/docs/contributing/security.md b/docs/contributing/security.md new file mode 100644 index 0000000000..a8ab8e7078 --- /dev/null +++ b/docs/contributing/security.md @@ -0,0 +1,29 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/security.md](../../packages/mermaid/src/docs/contributing/security.md). + +# Security + +The Mermaid team takes the security of Mermaid and the applications that use Mermaid seriously. This page describes how to report any vulnerabilities you may find, and lists best practices to minimize the risk of introducing a vulnerability. + +## Reporting vulnerabilities + +To report a vulnerability, please e-mail with a description of the issue, the steps you took to create the issue, affected versions, and if known, mitigations for the issue. + +We aim to reply within three working days, probably much sooner. + +You should expect a close collaboration as we work to resolve the issue you have reported. Please reach out to again if you do not receive prompt attention and regular updates. + +You may also reach out to the team via our public Slack chat channels; however, please make sure to e-mail when reporting an issue, and avoid revealing information about vulnerabilities in public as that could that could put users at risk. + +## Best practices + +Keep current with the latest Mermaid releases. We regularly update Mermaid, and these updates may fix security defects discovered in previous versions. Check the Mermaid release notes for security-related updates. + +Keep your application’s dependencies up to date. Make sure you upgrade your package dependencies to keep the dependencies up to date. Avoid pinning to specific versions for your dependencies and, if you do, make sure you check periodically to see if your dependencies have had security updates, and update the pin accordingly. + +## Configuring DomPurify + +By default Mermaid uses a baseline [DOMPurify](https://github.com/cure53/DOMPurify) config. It is possible to override the options passed to DOMPurify by adding a `dompurifyConfig` key to the Mermaid options. This could potentially break the output of Mermaid so use this with caution. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md new file mode 100644 index 0000000000..d43613c95d --- /dev/null +++ b/docs/contributing/setup.md @@ -0,0 +1,117 @@ +> **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 + + requirements[Install the requirements] + 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. + +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 +``` + +## Setup + +### 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.) diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md new file mode 100644 index 0000000000..881514371b --- /dev/null +++ b/docs/contributing/workflow.md @@ -0,0 +1,132 @@ +> **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. + +The basic steps to start contributing code and documentation are: + +```mermaid + flowchart TB + + fetch --> branch --> update --> submit --> review --> fetch + fetch[Fetch development branch] + branch[Checkout a new branch] + update[Make changes] + submit[Submit a PR] + review[Review and merge] +``` + +## Fech latest code + +> **💡 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` +``` + +## Checkout new branch + +Create a new branch for your work: + +```bash +git checkout develop # make sure you are on development branch +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`]\(() 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: + + Resolves # + +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. diff --git a/docs/config/Tutorials.md b/docs/ecosystem/tutorials.md similarity index 97% rename from docs/config/Tutorials.md rename to docs/ecosystem/tutorials.md index f3bad9adeb..36d5ad93fb 100644 --- a/docs/config/Tutorials.md +++ b/docs/ecosystem/tutorials.md @@ -2,7 +2,7 @@ > > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. > -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/Tutorials.md](../../packages/mermaid/src/docs/config/Tutorials.md). +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/ecosystem/tutorials.md](../../packages/mermaid/src/docs/ecosystem/tutorials.md). # Tutorials From 2705c0de0397740bc0302599aa79de9b126457b4 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Tue, 19 Dec 2023 03:56:16 +0300 Subject: [PATCH 08/39] Different fixes --- contrib.md | 78 +++ .../mermaid/src/docs/.vitepress/config.ts | 4 +- packages/mermaid/src/docs/community/code.md | 4 +- .../src/docs/community/contributing.md | 458 ++++++++++++++++-- .../src/docs/community/documentation.md | 31 +- packages/mermaid/src/docs/community/setup.md | 46 +- .../mermaid/src/docs/community/workflow.md | 4 +- 7 files changed, 539 insertions(+), 86 deletions(-) create mode 100644 contrib.md diff --git a/contrib.md b/contrib.md new file mode 100644 index 0000000000..843e9e6224 --- /dev/null +++ b/contrib.md @@ -0,0 +1,78 @@ +FIXME: remove before merge, this is previous contributing.md + +## 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 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 . + +#### 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) diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index ca5e49a1b5..b151e6175b 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -201,8 +201,8 @@ function sidebarCommunity() { collapsed: false, items: [ { text: 'Contributing to Mermaid', link: '/contributing/intro' }, - { text: 'Contributing guide', link: '/contributing/contributing' }, - { text: 'Initial setup', link: '/contributing/setup' }, + { text: 'Contributing Guide', link: '/contributing/contributing' }, + { text: 'Initial Setup', link: '/contributing/setup' }, { text: 'Workflow', link: '/contributing/workflow' }, { text: 'Code', link: '/contributing/code' }, { text: 'Documentation', link: '/contributing/documentation' }, diff --git a/packages/mermaid/src/docs/community/code.md b/packages/mermaid/src/docs/community/code.md index 129638da59..1c4f0946cb 100644 --- a/packages/mermaid/src/docs/community/code.md +++ b/packages/mermaid/src/docs/community/code.md @@ -107,8 +107,8 @@ it('should render forks and joins', () => { }); ``` -**_[TODO - running the tests against what is expected in development. ]_** -**_[TODO - how to generate new screenshots]_** + + ## Update Documentation diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 8bce7c2e9e..67b814d208 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -1,78 +1,456 @@ ---- -# Old Contributing Guide +# Mermaid 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) ---- +## Get the Source Code -# Mermaid contribution cheat-sheet +In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. -## Requirements +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 -## Development Installation +[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. -If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js: +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 -git clone git@github.com:mermaid-js/mermaid.git -cd mermaid +echo $DISPLAY ``` -Install required packages: +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 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 +npx pnpm install # npx is required for first install ``` -Open 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 . +#### 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.) + +## Workflow -### Docker +Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. -If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands: +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-nocode + flowchart TB + + fetch --> branch --> update --> submit --> review --> fetch + fetch[Fetch development branch] + branch[Checkout a new branch] + update[Make changes] + submit[Submit a PR] + review[Review and merge] +``` + +### Fech latest code + +```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` +``` + +### Checkout new branch + +Create a new branch for your work: + +```bash +git checkout develop # make sure you are on development branch +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-nocode +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). + +## Contributing Code + +Code it the heart of every software project. We strive to make it better. Who if not us? + +### Where is the code located? + +The core of Mermaid is located under `packages/mermaid/src`. + +### Running Mermaid Locally + +**Host** ```bash -./run install # npx pnpm install -./run test # pnpm test +npx pnpm run dev ``` -## Testing +**Docker** ```bash -# Run unit test +./run dev +``` + +After starting the dev server open in your browser. + +Now you are ready to make your changes! + +### Make Changes + +Have a look at . 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 . +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!) + +Edit files in `packages/mermaid/src` as required. + +### 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). + +Just as important, the tests act as _specifications:_ they specify what the code does (or should do). +Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. + +If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. +(If there had been a test for the situation, the bug never would have happened in the first place.) +You may need to change existing tests if they were inaccurate. + +If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. + +#### Unit Tests + +Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. + +Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) + +We use [Vitest](https://vitest.dev) to run unit tests. + +You can use the following command to run the unit tests: + +```sh pnpm test -# Run unit test in watch mode +``` + +When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: + +```sh pnpm test:watch -# Run E2E test -pnpm e2e -# Debug E2E tests -pnpm dev -pnpm cypress:open # in another terminal ``` -## Branch name format: +#### Integration/End-to-End (e2e) tests + +These test the rendering and visual appearance of the diagrams. +This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! + +To start working with the e2e tests: + +1. Run `pnpm dev` to start the dev server +2. Start **Cypress** by running `pnpm cypress:open`. + +The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. + +When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. + +This is what a rendering test looks like: + +```js +it('should render forks and joins', () => { + imgSnapshotTest( + ` + stateDiagram + state fork_state <<fork>> + [*] --> fork_state + fork_state --> State2 + fork_state --> State3 + + state join_state <<join>> + State2 --> join_state + State3 --> join_state + join_state --> State4 + State4 --> [*] + `, + { logLevel: 0 } + ); + cy.get('svg'); +}); +``` + + + + +### 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. + +The documentation has to be updated to users know that things have changed and added! +If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. + +eg: `# Feature Name (v+)` + +We know it can sometimes be hard to code _and_ write user documentation. + +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!) + +## 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? + +### Where is the Documentation Located? + +```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. +``` + +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"] +``` + +### Enable Github Actions + +```warning +So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first +``` + +### Running the Documentation Website Locally + +**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** + +Start development server for the documentation site + +**Host** + +```bash +pnpm --filter mermaid run docs:dev +``` + +or + +```bash +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. 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. + +```danger +Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. +``` + +````markdown +```note +This is a note +``` + +```tip +This is a tip +``` + +```warning +This is a warning +``` -```text - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] +```danger +This is a danger alert ``` +```` -eg: `feature/2945_state-diagram-new-arrow-florbs`, `bug/1123_fix_random_ugly_red_text` +### Documentation organization: Sidebar navigation -## Documentation +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). + +## 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 # +``` -Documentation is necessary for all non bugfix/refactoring changes. +You can edit it if needed. -Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +## Congratulations -**_DO NOT CHANGE FILES IN `/docs` MANUALLY_** +You have successfully submitted your improvements! What is next? -The `/docs` folder will be rebuilt and committed as part of a pre-commit hook. +- 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. -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs. diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index bd5acad120..b817fd2246 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -21,6 +21,12 @@ flowchart LR source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` +## Enable Github Actions + +```warning +So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first +``` + ## Running the Documentation Website Locally **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** @@ -35,7 +41,7 @@ pnpm --filter mermaid run docs:dev or -``` +```bash cd packages/mermaid pnpm docs:dev ``` @@ -50,39 +56,32 @@ Open [http://localhost:3333/](http://localhost:3333/) in your browser. ## Format -The documentation is written in Markdown. +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. + +```danger Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. +``` ````markdown ```note -Note content +This is a note ``` ```tip -Tip content +This is a tip ``` ```warning -Warning content +This is a warning ``` ```danger -Danger content +This is a danger alert ``` ```` -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). - -_[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. -2. Find the Markdown file (.md) to edit in the `packages/mermaid/src/docs` directory. -3. Make changes or add new documentation. -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. - ## 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.** diff --git a/packages/mermaid/src/docs/community/setup.md b/packages/mermaid/src/docs/community/setup.md index 8db29242c9..6a637cc4fd 100644 --- a/packages/mermaid/src/docs/community/setup.md +++ b/packages/mermaid/src/docs/community/setup.md @@ -6,17 +6,35 @@ Initial setup consists of 3 main steps: flowchart LR source --> requirements --> setup - requirements[Install the requirements] source[Get the source code] + requirements[Install the requirements] setup[Install packages] ``` -## Choose Your Environment +## Get the Source Code + +In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. +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: @@ -39,27 +57,7 @@ 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. - -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 -``` - -## Setup +## Install packages ### Host diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md index c0cf1c3e61..c707e5138a 100644 --- a/packages/mermaid/src/docs/community/workflow.md +++ b/packages/mermaid/src/docs/community/workflow.md @@ -114,8 +114,8 @@ Right now we are not following any strict rules about naming PRs. Give it a repr 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: -``` -Resolves # +```markdown +Resolves # ``` You can edit it if needed. From 37829696d880386fa6fb8a0e78e28b853225a25b Mon Sep 17 00:00:00 2001 From: nirname Date: Tue, 19 Dec 2023 00:59:26 +0000 Subject: [PATCH 09/39] Update docs --- docs/community/code.md | 5 +- docs/community/contributing.md | 453 ++++++++++++++++++++++++++--- docs/community/documentation.md | 35 ++- docs/community/setup.md | 46 ++- docs/community/workflow.md | 4 +- docs/contributing/code.md | 5 +- docs/contributing/contributing.md | 453 ++++++++++++++++++++++++++--- docs/contributing/documentation.md | 35 ++- docs/contributing/setup.md | 46 ++- docs/contributing/workflow.md | 4 +- 10 files changed, 924 insertions(+), 162 deletions(-) diff --git a/docs/community/code.md b/docs/community/code.md index 473a6da0e7..44cf4e062b 100644 --- a/docs/community/code.md +++ b/docs/community/code.md @@ -113,8 +113,9 @@ it('should render forks and joins', () => { }); ``` -**_\[TODO - running the tests against what is expected in development. ]_** -**_\[TODO - how to generate new screenshots]_** + + + ## Update Documentation diff --git a/docs/community/contributing.md b/docs/community/contributing.md index c50f4ea05d..5320681dcc 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -4,75 +4,456 @@ > > ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/contributing.md](../../packages/mermaid/src/docs/community/contributing.md). -# Mermaid contribution cheat-sheet +# Mermaid Contributing Guide -## Requirements +## 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 -## Development Installation +[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. -If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js: +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 -git clone git@github.com:mermaid-js/mermaid.git -cd mermaid +echo $DISPLAY ``` -Install required packages: +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 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 +npx pnpm install # npx is required for first install ``` -Open 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 . +#### 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. -### Docker +All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) -If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands: +## 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. + +The basic steps to start contributing code and documentation are: + +```mermaid + flowchart TB + + fetch --> branch --> update --> submit --> review --> fetch + fetch[Fetch development branch] + branch[Checkout a new branch] + update[Make changes] + submit[Submit a PR] + review[Review and merge] +``` + +### Fech latest code + +> **💡 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 -./run install # npx pnpm install -./run test # pnpm test +git checkout develop +git fetch # or `git pull` ``` -## Testing +### Checkout new branch + +Create a new branch for your work: ```bash -# Run unit test +git checkout develop # make sure you are on development branch +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`]\(() 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). + +## Contributing Code + +Code it the heart of every software project. We strive to make it better. Who if not us? + +### Where is the code located? + +The core of Mermaid is located under `packages/mermaid/src`. + +### Running Mermaid Locally + +**Host** + +```bash +npx pnpm run dev +``` + +**Docker** + +```bash +./run dev +``` + +After starting the dev server open in your browser. + +Now you are ready to make your changes! + +### Make Changes + +Have a look at . 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 . +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!) + +Edit files in `packages/mermaid/src` as required. + +### 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). + +Just as important, the tests act as _specifications:_ they specify what the code does (or should do). +Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. + +If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. +(If there had been a test for the situation, the bug never would have happened in the first place.) +You may need to change existing tests if they were inaccurate. + +If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. + +#### Unit Tests + +Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. + +Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) + +We use [Vitest](https://vitest.dev) to run unit tests. + +You can use the following command to run the unit tests: + +```sh pnpm test -# Run unit test in watch mode +``` + +When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: + +```sh pnpm test:watch -# Run E2E test -pnpm e2e -# Debug E2E tests -pnpm dev -pnpm cypress:open # in another terminal ``` -## Branch name format: +#### Integration/End-to-End (e2e) tests + +These test the rendering and visual appearance of the diagrams. +This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! + +To start working with the e2e tests: + +1. Run `pnpm dev` to start the dev server +2. Start **Cypress** by running `pnpm cypress:open`. + +The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. + +When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. + +This is what a rendering test looks like: + +```js +it('should render forks and joins', () => { + imgSnapshotTest( + ` + stateDiagram + state fork_state <<fork>> + [*] --> fork_state + fork_state --> State2 + fork_state --> State3 + + state join_state <<join>> + State2 --> join_state + State3 --> join_state + join_state --> State4 + State4 --> [*] + `, + { logLevel: 0 } + ); + cy.get('svg'); +}); +``` + + + + + +### 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. + +The documentation has to be updated to users know that things have changed and added! +If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. + +eg: `# Feature Name (v+)` + +We know it can sometimes be hard to code _and_ write user documentation. + +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!) + +## 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? + +### Where is the Documentation Located? + +> **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. + +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-example +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"] +``` + +```mermaid +flowchart LR + classDef default fill:#fff,color:black,stroke:black -```text - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] + source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` -eg: `feature/2945_state-diagram-new-arrow-florbs`, `bug/1123_fix_random_ugly_red_text` +### Enable Github Actions + +> **Warning** +> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first + +### Running the Documentation Website Locally + +**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** + +Start development server for the documentation site + +**Host** + +```bash +pnpm --filter mermaid run docs:dev +``` + +or + +```bash +cd packages/mermaid +pnpm docs:dev +``` + +**Docker** + + ./run docs:dev + +Open in your browser. -## Documentation +### Format + +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. + +> **‼️ Danger** +> Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. + +````markdown +```note +This is a note +``` + +```tip +This is a tip +``` + +```warning +This is a warning +``` + +```danger +This is a danger alert +``` +```` + +### 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.** + +The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). + +## 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 # +``` -Documentation is necessary for all non bugfix/refactoring changes. +You can edit it if needed. -Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +## Congratulations -**_DO NOT CHANGE FILES IN `/docs` MANUALLY_** +You have successfully submitted your improvements! What is next? -The `/docs` folder will be rebuilt and committed as part of a pre-commit hook. +- 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. -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs. diff --git a/docs/community/documentation.md b/docs/community/documentation.md index 28c7ede891..2b2cc0105e 100644 --- a/docs/community/documentation.md +++ b/docs/community/documentation.md @@ -33,6 +33,11 @@ flowchart LR source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` +## Enable Github Actions + +> **Warning** +> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first + ## Running the Documentation Website Locally **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** @@ -47,8 +52,10 @@ pnpm --filter mermaid run docs:dev or - cd packages/mermaid - pnpm docs:dev +```bash +cd packages/mermaid +pnpm docs:dev +``` **Docker** @@ -58,39 +65,31 @@ Open in your browser. ## Format -The documentation is written in Markdown. +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. -Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. + +> **‼️ Danger** +> Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. ````markdown ```note -Note content +This is a note ``` ```tip -Tip content +This is a tip ``` ```warning -Warning content +This is a warning ``` ```danger -Danger content +This is a danger alert ``` ```` -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). - -_\[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. -2. Find the Markdown file (.md) to edit in the `packages/mermaid/src/docs` directory. -3. Make changes or add new documentation. -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. - ## 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.** diff --git a/docs/community/setup.md b/docs/community/setup.md index 6fd4018929..33c13519d0 100644 --- a/docs/community/setup.md +++ b/docs/community/setup.md @@ -12,17 +12,35 @@ Initial setup consists of 3 main steps: flowchart LR source --> requirements --> setup - requirements[Install the requirements] source[Get the source code] + requirements[Install the requirements] setup[Install packages] ``` -## Choose Your Environment +## Get the Source Code + +In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. +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: @@ -45,27 +63,7 @@ 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. - -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 -``` - -## Setup +## Install packages ### Host diff --git a/docs/community/workflow.md b/docs/community/workflow.md index 0f142108b9..19d5ca165e 100644 --- a/docs/community/workflow.md +++ b/docs/community/workflow.md @@ -116,7 +116,9 @@ Right now we are not following any strict rules about naming PRs. Give it a repr 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: - Resolves # +```markdown +Resolves # +``` You can edit it if needed. diff --git a/docs/contributing/code.md b/docs/contributing/code.md index 435c8e6088..a3dbfcb2a9 100644 --- a/docs/contributing/code.md +++ b/docs/contributing/code.md @@ -113,8 +113,9 @@ it('should render forks and joins', () => { }); ``` -**_\[TODO - running the tests against what is expected in development. ]_** -**_\[TODO - how to generate new screenshots]_** + + + ## Update Documentation diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 4d48765107..ed0791ee88 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -4,75 +4,456 @@ > > ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/contributing.md](../../packages/mermaid/src/docs/contributing/contributing.md). -# Mermaid contribution cheat-sheet +# Mermaid Contributing Guide -## Requirements +## 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 -## Development Installation +[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. -If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js: +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 -git clone git@github.com:mermaid-js/mermaid.git -cd mermaid +echo $DISPLAY ``` -Install required packages: +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 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 +npx pnpm install # npx is required for first install ``` -Open 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 . +#### 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. -### Docker +All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) -If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands: +## 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. + +The basic steps to start contributing code and documentation are: + +```mermaid + flowchart TB + + fetch --> branch --> update --> submit --> review --> fetch + fetch[Fetch development branch] + branch[Checkout a new branch] + update[Make changes] + submit[Submit a PR] + review[Review and merge] +``` + +### Fech latest code + +> **💡 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 -./run install # npx pnpm install -./run test # pnpm test +git checkout develop +git fetch # or `git pull` ``` -## Testing +### Checkout new branch + +Create a new branch for your work: ```bash -# Run unit test +git checkout develop # make sure you are on development branch +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`]\(() 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). + +## Contributing Code + +Code it the heart of every software project. We strive to make it better. Who if not us? + +### Where is the code located? + +The core of Mermaid is located under `packages/mermaid/src`. + +### Running Mermaid Locally + +**Host** + +```bash +npx pnpm run dev +``` + +**Docker** + +```bash +./run dev +``` + +After starting the dev server open in your browser. + +Now you are ready to make your changes! + +### Make Changes + +Have a look at . 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 . +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!) + +Edit files in `packages/mermaid/src` as required. + +### 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). + +Just as important, the tests act as _specifications:_ they specify what the code does (or should do). +Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. + +If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. +(If there had been a test for the situation, the bug never would have happened in the first place.) +You may need to change existing tests if they were inaccurate. + +If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. + +#### Unit Tests + +Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. + +Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) + +We use [Vitest](https://vitest.dev) to run unit tests. + +You can use the following command to run the unit tests: + +```sh pnpm test -# Run unit test in watch mode +``` + +When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: + +```sh pnpm test:watch -# Run E2E test -pnpm e2e -# Debug E2E tests -pnpm dev -pnpm cypress:open # in another terminal ``` -## Branch name format: +#### Integration/End-to-End (e2e) tests + +These test the rendering and visual appearance of the diagrams. +This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! + +To start working with the e2e tests: + +1. Run `pnpm dev` to start the dev server +2. Start **Cypress** by running `pnpm cypress:open`. + +The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. + +When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. + +This is what a rendering test looks like: + +```js +it('should render forks and joins', () => { + imgSnapshotTest( + ` + stateDiagram + state fork_state <<fork>> + [*] --> fork_state + fork_state --> State2 + fork_state --> State3 + + state join_state <<join>> + State2 --> join_state + State3 --> join_state + join_state --> State4 + State4 --> [*] + `, + { logLevel: 0 } + ); + cy.get('svg'); +}); +``` + + + + + +### 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. + +The documentation has to be updated to users know that things have changed and added! +If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. + +eg: `# Feature Name (v+)` + +We know it can sometimes be hard to code _and_ write user documentation. + +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!) + +## 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? + +### Where is the Documentation Located? + +> **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. + +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-example +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"] +``` + +```mermaid +flowchart LR + classDef default fill:#fff,color:black,stroke:black -```text - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] + source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` -eg: `feature/2945_state-diagram-new-arrow-florbs`, `bug/1123_fix_random_ugly_red_text` +### Enable Github Actions + +> **Warning** +> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first + +### Running the Documentation Website Locally + +**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** + +Start development server for the documentation site + +**Host** + +```bash +pnpm --filter mermaid run docs:dev +``` + +or + +```bash +cd packages/mermaid +pnpm docs:dev +``` + +**Docker** + + ./run docs:dev + +Open in your browser. -## Documentation +### Format + +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. + +> **‼️ Danger** +> Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. + +````markdown +```note +This is a note +``` + +```tip +This is a tip +``` + +```warning +This is a warning +``` + +```danger +This is a danger alert +``` +```` + +### 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.** + +The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). + +## 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 # +``` -Documentation is necessary for all non bugfix/refactoring changes. +You can edit it if needed. -Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +## Congratulations -**_DO NOT CHANGE FILES IN `/docs` MANUALLY_** +You have successfully submitted your improvements! What is next? -The `/docs` folder will be rebuilt and committed as part of a pre-commit hook. +- 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. -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs. diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 8feda27994..17e787609d 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -33,6 +33,11 @@ flowchart LR source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` +## Enable Github Actions + +> **Warning** +> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first + ## Running the Documentation Website Locally **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** @@ -47,8 +52,10 @@ pnpm --filter mermaid run docs:dev or - cd packages/mermaid - pnpm docs:dev +```bash +cd packages/mermaid +pnpm docs:dev +``` **Docker** @@ -58,39 +65,31 @@ Open in your browser. ## Format -The documentation is written in Markdown. +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. -Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. + +> **‼️ Danger** +> Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. ````markdown ```note -Note content +This is a note ``` ```tip -Tip content +This is a tip ``` ```warning -Warning content +This is a warning ``` ```danger -Danger content +This is a danger alert ``` ```` -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). - -_\[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. -2. Find the Markdown file (.md) to edit in the `packages/mermaid/src/docs` directory. -3. Make changes or add new documentation. -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. - ## 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.** diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index d43613c95d..952eb8b692 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -12,17 +12,35 @@ Initial setup consists of 3 main steps: flowchart LR source --> requirements --> setup - requirements[Install the requirements] source[Get the source code] + requirements[Install the requirements] setup[Install packages] ``` -## Choose Your Environment +## Get the Source Code + +In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. +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: @@ -45,27 +63,7 @@ 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. - -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 -``` - -## Setup +## Install packages ### Host diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md index 881514371b..bb389bdb9f 100644 --- a/docs/contributing/workflow.md +++ b/docs/contributing/workflow.md @@ -116,7 +116,9 @@ Right now we are not following any strict rules about naming PRs. Give it a repr 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: - Resolves # +```markdown +Resolves # +``` You can edit it if needed. From d2b9240a22bc6ab96d550ed92989aebcf3472254 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Tue, 19 Dec 2023 04:33:32 +0300 Subject: [PATCH 10/39] Simplify things --- packages/mermaid/src/docs/community/code.md | 2 +- .../src/docs/community/contributing.md | 40 +++++++++++-------- .../src/docs/community/documentation.md | 4 +- .../mermaid/src/docs/community/workflow.md | 10 +---- 4 files changed, 28 insertions(+), 28 deletions(-) diff --git a/packages/mermaid/src/docs/community/code.md b/packages/mermaid/src/docs/community/code.md index 1c4f0946cb..2b4d249621 100644 --- a/packages/mermaid/src/docs/community/code.md +++ b/packages/mermaid/src/docs/community/code.md @@ -2,7 +2,7 @@ Code it the heart of every software project. We strive to make it better. Who if not us? -## Where is the code located? +## Where is the Code Located? The core of Mermaid is located under `packages/mermaid/src`. diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 67b814d208..eb2c03ce1d 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -1,6 +1,23 @@ # Mermaid Contributing Guide -## Get the Source Code +You decided to take part in the development? Welcome! + +We were trying to make our guidelines for you as explicit and detailed as possible. + +## Initial Setup + +Initial setup consists of 3 main steps: + +```mermaid-nocode +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. @@ -20,7 +37,7 @@ Once you have cloned the repository onto your development machine, change into t cd mermaid ``` -## Install Requirements +### Install Requirements We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. @@ -113,15 +130,14 @@ The basic steps to start contributing code and documentation are: ```mermaid-nocode flowchart TB - fetch --> branch --> update --> submit --> review --> fetch - fetch[Fetch development branch] + branch --> update --> submit --> review --> branch branch[Checkout a new branch] update[Make changes] submit[Submit a PR] review[Review and merge] ``` -### Fech latest code +## Checkout a New Branch ```tip All new work should be based on the `develop` branch. @@ -136,12 +152,9 @@ git checkout develop git fetch # or `git pull` ``` -### Checkout new branch - Create a new branch for your work: ```bash -git checkout develop # make sure you are on development branch git checkout -b docs/2910_update-contributing-guidelines ``` @@ -191,13 +204,6 @@ A bug described in issue 1123 that causes random ugly red text in multiple diagr `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). - ## Contributing Code Code it the heart of every software project. We strive to make it better. Who if not us? @@ -344,7 +350,7 @@ 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. +Documentation 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. @@ -416,7 +422,7 @@ This is a danger alert ``` ```` -### Documentation organization: Sidebar navigation +### 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.** diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index b817fd2246..30702ea36b 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -10,7 +10,7 @@ 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. +Documentation 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. @@ -82,7 +82,7 @@ This is a danger alert ``` ```` -## Documentation organization: Sidebar navigation +## 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.** diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md index c707e5138a..5783125f9b 100644 --- a/packages/mermaid/src/docs/community/workflow.md +++ b/packages/mermaid/src/docs/community/workflow.md @@ -8,20 +8,17 @@ Once development is done we create a `release/vX.X.X` branch from `develop` for 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-nocode flowchart TB - fetch --> branch --> update --> submit --> review --> fetch - fetch[Fetch development branch] + branch --> update --> submit --> review --> branch branch[Checkout a new branch] update[Make changes] submit[Submit a PR] review[Review and merge] ``` -## Fech latest code +## Checkout a New Branch ```tip All new work should be based on the `develop` branch. @@ -36,12 +33,9 @@ git checkout develop git fetch # or `git pull` ``` -## Checkout new branch - Create a new branch for your work: ```bash -git checkout develop # make sure you are on development branch git checkout -b docs/2910_update-contributing-guidelines ``` From 97ee5a8488f87847462ade884031c649085b6683 Mon Sep 17 00:00:00 2001 From: nirname Date: Tue, 19 Dec 2023 01:36:43 +0000 Subject: [PATCH 11/39] Update docs --- docs/community/code.md | 2 +- docs/community/contributing.md | 40 +++++++++++++++++------------- docs/community/documentation.md | 4 +-- docs/community/workflow.md | 10 ++------ docs/contributing/code.md | 2 +- docs/contributing/contributing.md | 40 +++++++++++++++++------------- docs/contributing/documentation.md | 4 +-- docs/contributing/workflow.md | 10 ++------ 8 files changed, 56 insertions(+), 56 deletions(-) diff --git a/docs/community/code.md b/docs/community/code.md index 44cf4e062b..c7f3647356 100644 --- a/docs/community/code.md +++ b/docs/community/code.md @@ -8,7 +8,7 @@ Code it the heart of every software project. We strive to make it better. Who if not us? -## Where is the code located? +## Where is the Code Located? The core of Mermaid is located under `packages/mermaid/src`. diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 5320681dcc..8218f31caf 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -6,7 +6,24 @@ # Mermaid Contributing Guide -## Get the Source Code +You decided to take part in the development? Welcome! + +We were trying to make our guidelines for you as explicit and detailed as possible. + +## 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. @@ -26,7 +43,7 @@ Once you have cloned the repository onto your development machine, change into t cd mermaid ``` -## Install Requirements +### Install Requirements We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. @@ -118,15 +135,14 @@ The basic steps to start contributing code and documentation are: ```mermaid flowchart TB - fetch --> branch --> update --> submit --> review --> fetch - fetch[Fetch development branch] + branch --> update --> submit --> review --> branch branch[Checkout a new branch] update[Make changes] submit[Submit a PR] review[Review and merge] ``` -### Fech latest code +## Checkout a New Branch > **💡 Tip** > All new work should be based on the `develop` branch. @@ -140,12 +156,9 @@ git checkout develop git fetch # or `git pull` ``` -### Checkout new branch - Create a new branch for your work: ```bash -git checkout develop # make sure you are on development branch git checkout -b docs/2910_update-contributing-guidelines ``` @@ -193,13 +206,6 @@ If your work is specific to a single diagram type, it is a good idea to put the > > `bug/1123_fix_random_ugly_red_text` -### Make changes - -Source code and the documentation are located \[`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). - ## Contributing Code Code it the heart of every software project. We strive to make it better. Who if not us? @@ -345,7 +351,7 @@ If it is not in the documentation, it's like it never happened. Wouldn't that be > > 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. +Documentation 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. @@ -420,7 +426,7 @@ This is a danger alert ``` ```` -### Documentation organization: Sidebar navigation +### 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.** diff --git a/docs/community/documentation.md b/docs/community/documentation.md index 2b2cc0105e..a321c882cc 100644 --- a/docs/community/documentation.md +++ b/docs/community/documentation.md @@ -15,7 +15,7 @@ If it is not in the documentation, it's like it never happened. Wouldn't that be > > 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. +Documentation 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. @@ -90,7 +90,7 @@ This is a danger alert ``` ```` -## Documentation organization: Sidebar navigation +## 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.** diff --git a/docs/community/workflow.md b/docs/community/workflow.md index 19d5ca165e..2ccc36e050 100644 --- a/docs/community/workflow.md +++ b/docs/community/workflow.md @@ -14,20 +14,17 @@ Once development is done we create a `release/vX.X.X` branch from `develop` for 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 - fetch --> branch --> update --> submit --> review --> fetch - fetch[Fetch development branch] + branch --> update --> submit --> review --> branch branch[Checkout a new branch] update[Make changes] submit[Submit a PR] review[Review and merge] ``` -## Fech latest code +## Checkout a New Branch > **💡 Tip** > All new work should be based on the `develop` branch. @@ -41,12 +38,9 @@ git checkout develop git fetch # or `git pull` ``` -## Checkout new branch - Create a new branch for your work: ```bash -git checkout develop # make sure you are on development branch git checkout -b docs/2910_update-contributing-guidelines ``` diff --git a/docs/contributing/code.md b/docs/contributing/code.md index a3dbfcb2a9..73fc89f27a 100644 --- a/docs/contributing/code.md +++ b/docs/contributing/code.md @@ -8,7 +8,7 @@ Code it the heart of every software project. We strive to make it better. Who if not us? -## Where is the code located? +## Where is the Code Located? The core of Mermaid is located under `packages/mermaid/src`. diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index ed0791ee88..af5388af34 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -6,7 +6,24 @@ # Mermaid Contributing Guide -## Get the Source Code +You decided to take part in the development? Welcome! + +We were trying to make our guidelines for you as explicit and detailed as possible. + +## 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. @@ -26,7 +43,7 @@ Once you have cloned the repository onto your development machine, change into t cd mermaid ``` -## Install Requirements +### Install Requirements We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. @@ -118,15 +135,14 @@ The basic steps to start contributing code and documentation are: ```mermaid flowchart TB - fetch --> branch --> update --> submit --> review --> fetch - fetch[Fetch development branch] + branch --> update --> submit --> review --> branch branch[Checkout a new branch] update[Make changes] submit[Submit a PR] review[Review and merge] ``` -### Fech latest code +## Checkout a New Branch > **💡 Tip** > All new work should be based on the `develop` branch. @@ -140,12 +156,9 @@ git checkout develop git fetch # or `git pull` ``` -### Checkout new branch - Create a new branch for your work: ```bash -git checkout develop # make sure you are on development branch git checkout -b docs/2910_update-contributing-guidelines ``` @@ -193,13 +206,6 @@ If your work is specific to a single diagram type, it is a good idea to put the > > `bug/1123_fix_random_ugly_red_text` -### Make changes - -Source code and the documentation are located \[`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). - ## Contributing Code Code it the heart of every software project. We strive to make it better. Who if not us? @@ -345,7 +351,7 @@ If it is not in the documentation, it's like it never happened. Wouldn't that be > > 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. +Documentation 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. @@ -420,7 +426,7 @@ This is a danger alert ``` ```` -### Documentation organization: Sidebar navigation +### 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.** diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 17e787609d..59fb3a9413 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -15,7 +15,7 @@ If it is not in the documentation, it's like it never happened. Wouldn't that be > > 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. +Documentation 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. @@ -90,7 +90,7 @@ This is a danger alert ``` ```` -## Documentation organization: Sidebar navigation +## 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.** diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md index bb389bdb9f..f31cc8afab 100644 --- a/docs/contributing/workflow.md +++ b/docs/contributing/workflow.md @@ -14,20 +14,17 @@ Once development is done we create a `release/vX.X.X` branch from `develop` for 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 - fetch --> branch --> update --> submit --> review --> fetch - fetch[Fetch development branch] + branch --> update --> submit --> review --> branch branch[Checkout a new branch] update[Make changes] submit[Submit a PR] review[Review and merge] ``` -## Fech latest code +## Checkout a New Branch > **💡 Tip** > All new work should be based on the `develop` branch. @@ -41,12 +38,9 @@ git checkout develop git fetch # or `git pull` ``` -## Checkout new branch - Create a new branch for your work: ```bash -git checkout develop # make sure you are on development branch git checkout -b docs/2910_update-contributing-guidelines ``` From dfa0ad5b7a5d86ca7e4c6fe2d2a32e77aeac29f2 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Thu, 21 Dec 2023 03:40:50 +0300 Subject: [PATCH 12/39] Refined contribution guide again --- .../mermaid/src/docs/.vitepress/config.ts | 4 +- .../src/docs/community/contributing.md | 93 +++++++++++++------ .../src/docs/community/documentation.md | 2 +- 3 files changed, 66 insertions(+), 33 deletions(-) diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index b151e6175b..4cd9e28437 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -75,12 +75,12 @@ function nav() { { text: 'Tutorials', link: '/ecosystem/tutorials', - activeMatch: '/ecosystem/', + activeMatch: '/ecosystem/tutorials', }, { text: 'Integrations', link: '/ecosystem/integrations-community', - activeMatch: '/ecosystem/', + activeMatch: '/ecosystem/integrations-community', }, { text: 'Contributing', diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index eb2c03ce1d..57f6040802 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -12,9 +12,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 @@ -41,7 +41,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: @@ -50,7 +50,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. @@ -63,9 +63,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. @@ -73,7 +73,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. @@ -113,29 +113,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 -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. +Contributing process is very simple and strightforward: -Development is done in the `develop` branch. +```mermaid-nocode + flowchart LR -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. + branch --> changes --> submit + branch[Checkout a New Branch] + changes[Make Changes] + submit[Submit a PR] +``` -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 uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. -The basic steps to start contributing code and documentation are: +Development is done in the `develop` branch. ```mermaid-nocode - 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 @@ -388,13 +407,13 @@ pnpm docs:dev **Docker** -``` +```bash ./run docs:dev ``` Open [http://localhost:3333/](http://localhost:3333/) 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). @@ -404,6 +423,8 @@ You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a n 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 @@ -422,11 +443,25 @@ This is a danger alert ``` ```` -### Navigation +```note +This is a note +``` -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.** +```tip +This is a tip +``` -The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). +```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**, which is defined in [the vitepress config](../.vitepress/config.ts). The same goes to **topbar**. ## Submit your pull request @@ -440,7 +475,7 @@ 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. +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: @@ -448,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/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index 30702ea36b..ce11369735 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -48,7 +48,7 @@ pnpm docs:dev **Docker** -``` +```bash ./run docs:dev ``` From d54d13ef2875c3f8d1b9066ee6791ae21805fce0 Mon Sep 17 00:00:00 2001 From: nirname Date: Thu, 21 Dec 2023 00:44:22 +0000 Subject: [PATCH 13/39] Update docs --- docs/community/contributing.md | 88 ++++++++++++++++++++---------- docs/community/documentation.md | 4 +- docs/contributing/contributing.md | 88 ++++++++++++++++++++---------- docs/contributing/documentation.md | 4 +- 4 files changed, 124 insertions(+), 60 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 8218f31caf..9f2af00928 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 -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. +Contributing process is very simple and strightforward: -Development is done in the `develop` branch. +```mermaid + flowchart LR -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. + branch --> changes --> submit + branch[Checkout a New Branch] + changes[Make Changes] + submit[Submit a PR] +``` -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 uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. -The basic steps to start contributing code and documentation are: +Development is done in the `develop` 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] +--- +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 ``` ```` -### Navigation +> **Note** +> This is a note + +> **💡 Tip** +> This is a tip -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.** +> **Warning** +> This is a warning -The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). +> **‼️ 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**, 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 a321c882cc..cd9fb277c3 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 af5388af34..595fccf0ac 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 -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. +Contributing process is very simple and strightforward: -Development is done in the `develop` branch. +```mermaid + flowchart LR -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. + branch --> changes --> submit + branch[Checkout a New Branch] + changes[Make Changes] + submit[Submit a PR] +``` -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 uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. -The basic steps to start contributing code and documentation are: +Development is done in the `develop` 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] +--- +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 ``` ```` -### Navigation +> **Note** +> This is a note + +> **💡 Tip** +> This is a tip -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.** +> **Warning** +> This is a warning -The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts). +> **‼️ 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**, 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 59fb3a9413..550adc6d3a 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. From 807a5bfab4219a9e9ae67550ea6d31ea5100b5ac Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Thu, 4 Jan 2024 03:37:41 +0300 Subject: [PATCH 14/39] Batch of small improvements for the documentation --- docker-compose.yml | 4 +- .../mermaid/src/docs/.vitepress/config.ts | 10 +- packages/mermaid/src/docs/community/code.md | 133 ------------------ .../src/docs/community/contributing.md | 37 +++-- .../src/docs/community/documentation.md | 89 ------------ packages/mermaid/src/docs/community/intro.md | 32 +++-- .../community/questions-and-suggestions.md | 12 +- 7 files changed, 58 insertions(+), 259 deletions(-) delete mode 100644 packages/mermaid/src/docs/community/code.md delete mode 100644 packages/mermaid/src/docs/community/documentation.md diff --git a/docker-compose.yml b/docker-compose.yml index 6f8d4c6b73..733f5d9a72 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,9 +5,9 @@ services: stdin_open: true tty: true working_dir: /mermaid - mem_limit: '6G' + mem_limit: '8G' environment: - - NODE_OPTIONS=--max_old_space_size=6096 + - NODE_OPTIONS=--max_old_space_size=8192 volumes: - ./:/mermaid - root_cache:/root/.cache diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index 4cd9e28437..c7d29b277f 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -200,14 +200,10 @@ function sidebarCommunity() { text: '🙌 Contributing', collapsed: false, items: [ - { text: 'Contributing to Mermaid', link: '/contributing/intro' }, - { text: 'Contributing Guide', link: '/contributing/contributing' }, - { text: 'Initial Setup', link: '/contributing/setup' }, - { text: 'Workflow', link: '/contributing/workflow' }, - { text: 'Code', link: '/contributing/code' }, - { text: 'Documentation', link: '/contributing/documentation' }, - { text: 'Questions and Suggestions', link: '/contributing/questions-and-suggestions' }, + { text: 'Getting Started', link: '/contributing/intro' }, + { text: 'Contributing to Mermaid', link: '/contributing/contributing' }, { text: 'Adding Diagrams', link: '/contributing/new-diagram' }, + { text: 'Questions and Suggestions', link: '/contributing/questions-and-suggestions' }, { text: 'Security', link: '/contributing/security' }, ], }, diff --git a/packages/mermaid/src/docs/community/code.md b/packages/mermaid/src/docs/community/code.md deleted file mode 100644 index 2b4d249621..0000000000 --- a/packages/mermaid/src/docs/community/code.md +++ /dev/null @@ -1,133 +0,0 @@ -# Contributing Code - -Code it the heart of every software project. We strive to make it better. Who if not us? - -## Where is the Code Located? - -The core of Mermaid is located under `packages/mermaid/src`. - -## Running Mermaid Locally - -**Host** - -```bash -npx pnpm run dev -``` - -**Docker** - -```bash -./run dev -``` - -After starting the dev server open in your browser. - -Now you are ready to make your changes! - -## Make Changes - -Have a look at . 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 . -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!) - -Edit files in `packages/mermaid/src` as required. - -## 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). - -Just as important, the tests act as _specifications:_ they specify what the code does (or should do). -Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. - -If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. -(If there had been a test for the situation, the bug never would have happened in the first place.) -You may need to change existing tests if they were inaccurate. - -If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. - -### Unit Tests - -Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. - -Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) - -We use [Vitest](https://vitest.dev) to run unit tests. - -You can use the following command to run the unit tests: - -```sh -pnpm test -``` - -When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: - -```sh -pnpm test:watch -``` - -### Integration/End-to-End (e2e) tests - -These test the rendering and visual appearance of the diagrams. -This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! - -To start working with the e2e tests: - -1. Run `pnpm dev` to start the dev server -2. Start **Cypress** by running `pnpm cypress:open`. - -The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. - -When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. - -This is what a rendering test looks like: - -```js -it('should render forks and joins', () => { - imgSnapshotTest( - ` - stateDiagram - state fork_state <<fork>> - [*] --> fork_state - fork_state --> State2 - fork_state --> State3 - - state join_state <<join>> - State2 --> join_state - State3 --> join_state - join_state --> State4 - State4 --> [*] - `, - { logLevel: 0 } - ); - cy.get('svg'); -}); -``` - - - - -## 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. - -The documentation has to be updated to users know that things have changed and added! -If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. - -eg: `# Feature Name (v+)` - -We know it can sometimes be hard to code _and_ write user documentation. - -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!) diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 57f6040802..71a4f4b2dc 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -19,13 +19,13 @@ flowchart LR ### Get the Source Code -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. +In GitHub, you first [**fork a mermaid repository**](https://github.com/mermaid-js/mermaid/fork) 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). - +```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 git@github.com/your-fork/mermaid @@ -227,7 +227,7 @@ A bug described in issue 1123 that causes random ugly red text in multiple diagr Code it the heart of every software project. We strive to make it better. Who if not us? -### Where is the code located? +### Where is the Code Located? The core of Mermaid is located under `packages/mermaid/src`. @@ -262,8 +262,7 @@ Edit files in `packages/mermaid/src` as required. ### 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). +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). Just as important, the tests act as _specifications:_ they specify what the code does (or should do). Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. @@ -282,6 +281,8 @@ Unit tests are mandatory all code except the renderers. (The renderers are teste We use [Vitest](https://vitest.dev) to run unit tests. +**Host** + You can use the following command to run the unit tests: ```sh @@ -294,6 +295,14 @@ When writing new tests, it's easier to have the tests automatically run as you m pnpm test:watch ``` +**Docker** + +When using Docker prepend your command with `./run`: + +```sh +./run pnpm test +``` + #### Integration/End-to-End (e2e) tests These test the rendering and visual appearance of the diagrams. @@ -301,8 +310,16 @@ This ensures that the rendering of that feature in the e2e will be reviewed in t To start working with the e2e tests: -1. Run `pnpm dev` to start the dev server -2. Start **Cypress** by running `pnpm cypress:open`. +**Host** + +- Run `pnpm dev` to start the dev server +- Start **Cypress** by running `pnpm cypress:open`. + +**Docker** + +- Enable local connections for x11 server `xhost +local:` +- Run `./run pnpm dev` to start the dev server +- Start **Cypress** by running `./run pnpm cypress:open --project .`. The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. @@ -469,7 +486,7 @@ If you want to propose changes to how the documentation is _organized_, such as Do not forget to push your changes ```bash -git push -u origin docs/2910_update-contributing-guidelines +git push -u origin docs/2910_update-guidelines ``` ```` @@ -492,4 +509,4 @@ You have successfully submitted your improvements! What is next? - 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. +Thanks for you help! diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md deleted file mode 100644 index ce11369735..0000000000 --- a/packages/mermaid/src/docs/community/documentation.md +++ /dev/null @@ -1,89 +0,0 @@ -# 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? - -## Where is the Documentation Located? - -```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. -``` - -Documentation 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"] -``` - -## Enable Github Actions - -```warning -So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first -``` - -## Running the Documentation Website Locally - -**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** - -Start development server for the documentation site - -**Host** - -```bash -pnpm --filter mermaid run docs:dev -``` - -or - -```bash -cd packages/mermaid -pnpm docs:dev -``` - -**Docker** - -```bash -./run docs:dev -``` - -Open [http://localhost:3333/](http://localhost:3333/) in your browser. - -## Format - -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. - -```danger -Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. -``` - -````markdown -```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). diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 7ff1ced1e5..e700fde45c 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -1,4 +1,4 @@ -# Contributing to Mermaid +# Getting Started So you want to help? That's great! @@ -25,21 +25,29 @@ 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). +```tip +**Check out our** [**detailed contribution guide**](./contributing.md). +``` + +Where to start: + +- You could start getting some knowledge of the code base by working on [these "good first issues"](https://github.com/mermaid-js/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22+). +- You could jump right in and help us fix any of [these bugs](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug+%2F+Error%22++label%3A%22Contributor+needed%22+)! +- You could help write and [improve the documentation](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). +- You could work on a new feature! [These](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22+) are some ideas! +- You could confirm the bugs in [these issues](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Status%3A+Triage%22++label%3A%22Type%3A+Bug+%2F+Error%22). - - +[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) -## Where do I start? +## A Question Or a Suggestion? + +```tip +**Have a look at** [**how to open an issue**](./questions-and-suggestions.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+). -- You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! -- You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! -- [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +If you have faced a vulnerability [report it to us](./security.md). ## Last Words diff --git a/packages/mermaid/src/docs/community/questions-and-suggestions.md b/packages/mermaid/src/docs/community/questions-and-suggestions.md index 386e3753a1..6408d7fed1 100644 --- a/packages/mermaid/src/docs/community/questions-and-suggestions.md +++ b/packages/mermaid/src/docs/community/questions-and-suggestions.md @@ -1,19 +1,19 @@ # Questions or Suggestions? -**_[TODO: This section is still a WIP. It still needs MAJOR revision.]_** +## Search for Existing Issue -## First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. +First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. - [Search in Discussions](https://github.com/orgs/mermaid-js/discussions) - [Search in Issues (Open & Closed)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue) If you find an open issue or discussion thread that is similar to your question but isn't answered, you can let us know that you are also interested in it. -Use the GitHub reactions to add a thumbs-up to the issue or discussion thread. +Use the GitHub reactions to add a thumbs-up to the issue or discussion thread, or append to the issue if needed. This helps the team know the relative interest in something and helps them set priorities and assignments. -Feel free to add to the discussion on the issue or topic. +## Add a new Issue -If you can't find anything that already addresses your question or suggestion, _open a new issue:_ +You have not found anything that already addresses your request, or maybe you have come up with the new idea? Feel free to open a new issue or discussion. -Log in to [GitHub.com](https://www.github.com), open or append to an issue [using the GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). +Log in to [GitHub.com](https://www.github.com), and use [GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues). Press [https://github.com/mermaid-js/mermaid/issues/new/choose] issue, select the appropriate template and describe your problem. From 8edf96fe1cdfec54f6023ecdee88f575f907d9c9 Mon Sep 17 00:00:00 2001 From: nirname Date: Thu, 4 Jan 2024 00:41:07 +0000 Subject: [PATCH 15/39] Update docs --- docs/community/code.md | 139 ------------------ docs/community/contributing.md | 37 +++-- docs/community/documentation.md | 99 ------------- docs/community/intro.md | 27 ++-- docs/community/questions-and-suggestions.md | 12 +- docs/contributing/code.md | 139 ------------------ docs/contributing/contributing.md | 37 +++-- docs/contributing/documentation.md | 99 ------------- docs/contributing/intro.md | 27 ++-- .../contributing/questions-and-suggestions.md | 12 +- 10 files changed, 94 insertions(+), 534 deletions(-) delete mode 100644 docs/community/code.md delete mode 100644 docs/community/documentation.md delete mode 100644 docs/contributing/code.md delete mode 100644 docs/contributing/documentation.md diff --git a/docs/community/code.md b/docs/community/code.md deleted file mode 100644 index c7f3647356..0000000000 --- a/docs/community/code.md +++ /dev/null @@ -1,139 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/code.md](../../packages/mermaid/src/docs/community/code.md). - -# Contributing Code - -Code it the heart of every software project. We strive to make it better. Who if not us? - -## Where is the Code Located? - -The core of Mermaid is located under `packages/mermaid/src`. - -## Running Mermaid Locally - -**Host** - -```bash -npx pnpm run dev -``` - -**Docker** - -```bash -./run dev -``` - -After starting the dev server open in your browser. - -Now you are ready to make your changes! - -## Make Changes - -Have a look at . 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 . -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!) - -Edit files in `packages/mermaid/src` as required. - -## 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). - -Just as important, the tests act as _specifications:_ they specify what the code does (or should do). -Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. - -If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. -(If there had been a test for the situation, the bug never would have happened in the first place.) -You may need to change existing tests if they were inaccurate. - -If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. - -### Unit Tests - -Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. - -Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) - -We use [Vitest](https://vitest.dev) to run unit tests. - -You can use the following command to run the unit tests: - -```sh -pnpm test -``` - -When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: - -```sh -pnpm test:watch -``` - -### Integration/End-to-End (e2e) tests - -These test the rendering and visual appearance of the diagrams. -This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! - -To start working with the e2e tests: - -1. Run `pnpm dev` to start the dev server -2. Start **Cypress** by running `pnpm cypress:open`. - -The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. - -When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. - -This is what a rendering test looks like: - -```js -it('should render forks and joins', () => { - imgSnapshotTest( - ` - stateDiagram - state fork_state <<fork>> - [*] --> fork_state - fork_state --> State2 - fork_state --> State3 - - state join_state <<join>> - State2 --> join_state - State3 --> join_state - join_state --> State4 - State4 --> [*] - `, - { logLevel: 0 } - ); - cy.get('svg'); -}); -``` - - - - - -## 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. - -The documentation has to be updated to users know that things have changed and added! -If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. - -eg: `# Feature Name (v+)` - -We know it can sometimes be hard to code _and_ write user documentation. - -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!) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 9f2af00928..5eb17ead95 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -25,13 +25,11 @@ flowchart LR ### Get the Source Code -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. +In GitHub, you first [**fork a mermaid repository**](https://github.com/mermaid-js/mermaid/fork) 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). +> **💡 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 git@github.com/your-fork/mermaid @@ -228,7 +226,7 @@ If your work is specific to a single diagram type, it is a good idea to put the Code it the heart of every software project. We strive to make it better. Who if not us? -### Where is the code located? +### Where is the Code Located? The core of Mermaid is located under `packages/mermaid/src`. @@ -263,8 +261,7 @@ Edit files in `packages/mermaid/src` as required. ### 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). +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). Just as important, the tests act as _specifications:_ they specify what the code does (or should do). Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. @@ -283,6 +280,8 @@ Unit tests are mandatory all code except the renderers. (The renderers are teste We use [Vitest](https://vitest.dev) to run unit tests. +**Host** + You can use the following command to run the unit tests: ```sh @@ -295,6 +294,14 @@ When writing new tests, it's easier to have the tests automatically run as you m pnpm test:watch ``` +**Docker** + +When using Docker prepend your command with `./run`: + +```sh +./run pnpm test +``` + #### Integration/End-to-End (e2e) tests These test the rendering and visual appearance of the diagrams. @@ -302,8 +309,16 @@ This ensures that the rendering of that feature in the e2e will be reviewed in t To start working with the e2e tests: -1. Run `pnpm dev` to start the dev server -2. Start **Cypress** by running `pnpm cypress:open`. +**Host** + +- Run `pnpm dev` to start the dev server +- Start **Cypress** by running `pnpm cypress:open`. + +**Docker** + +- Enable local connections for x11 server `xhost +local:` +- Run `./run pnpm dev` to start the dev server +- Start **Cypress** by running `./run pnpm cypress:open --project .`. The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. @@ -470,7 +485,7 @@ If you want to propose changes to how the documentation is _organized_, such as > Do not forget to push your changes > > ```bash -> git push -u origin docs/2910_update-contributing-guidelines +> git push -u origin docs/2910_update-guidelines > ``` We make all changes via Pull Requests (PRs). Open a new one. @@ -492,4 +507,4 @@ You have successfully submitted your improvements! What is next? - 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. +Thanks for you help! diff --git a/docs/community/documentation.md b/docs/community/documentation.md deleted file mode 100644 index cd9fb277c3..0000000000 --- a/docs/community/documentation.md +++ /dev/null @@ -1,99 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/documentation.md](../../packages/mermaid/src/docs/community/documentation.md). - -# 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? - -## Where is the Documentation Located? - -> **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. - -Documentation 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-example -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"] -``` - -```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"] -``` - -## Enable Github Actions - -> **Warning** -> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first - -## Running the Documentation Website Locally - -**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** - -Start development server for the documentation site - -**Host** - -```bash -pnpm --filter mermaid run docs:dev -``` - -or - -```bash -cd packages/mermaid -pnpm docs:dev -``` - -**Docker** - -```bash -./run docs:dev -``` - -Open in your browser. - -## Format - -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. - -> **‼️ Danger** -> Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. - -````markdown -```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). diff --git a/docs/community/intro.md b/docs/community/intro.md index 73392e62c6..9f515f8c0f 100644 --- a/docs/community/intro.md +++ b/docs/community/intro.md @@ -4,7 +4,7 @@ > > ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/intro.md](../../packages/mermaid/src/docs/community/intro.md). -# Contributing to Mermaid +# Getting Started So you want to help? That's great! @@ -31,22 +31,25 @@ 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). +> **💡 Tip** > **Check out our** [**detailed contribution guide**](./contributing.md). - +Where to start: - +- You could start getting some knowledge of the code base by working on [these "good first issues"](https://github.com/mermaid-js/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22+). +- You could jump right in and help us fix any of [these bugs](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug+%2F+Error%22++label%3A%22Contributor+needed%22+)! +- You could help write and [improve the documentation](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). +- You could work on a new feature! [These](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22+) are some ideas! +- You could confirm the bugs in [these issues](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Status%3A+Triage%22++label%3A%22Type%3A+Bug+%2F+Error%22). -## Where do I start? +[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) -- 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+). -- You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! -- You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! -- [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +## A Question Or a Suggestion? + +> **💡 Tip** > **Have a look at** [**how to open an issue**](./questions-and-suggestions.md). + +If you have faced a vulnerability [report it to us](./security.md). ## Last Words diff --git a/docs/community/questions-and-suggestions.md b/docs/community/questions-and-suggestions.md index badb53a35a..8dbfae0080 100644 --- a/docs/community/questions-and-suggestions.md +++ b/docs/community/questions-and-suggestions.md @@ -6,20 +6,20 @@ # Questions or Suggestions? -**_\[TODO: This section is still a WIP. It still needs MAJOR revision.]_** +## Search for Existing Issue -## First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. +First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. - [Search in Discussions](https://github.com/orgs/mermaid-js/discussions) - [Search in Issues (Open & Closed)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue) If you find an open issue or discussion thread that is similar to your question but isn't answered, you can let us know that you are also interested in it. -Use the GitHub reactions to add a thumbs-up to the issue or discussion thread. +Use the GitHub reactions to add a thumbs-up to the issue or discussion thread, or append to the issue if needed. This helps the team know the relative interest in something and helps them set priorities and assignments. -Feel free to add to the discussion on the issue or topic. +## Add a new Issue -If you can't find anything that already addresses your question or suggestion, _open a new issue:_ +You have not found anything that already addresses your request, or maybe you have come up with the new idea? Feel free to open a new issue or discussion. -Log in to [GitHub.com](https://www.github.com), open or append to an issue [using the GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). +Log in to [GitHub.com](https://www.github.com), and use [GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues). Press \[] issue, select the appropriate template and describe your problem. diff --git a/docs/contributing/code.md b/docs/contributing/code.md deleted file mode 100644 index 73fc89f27a..0000000000 --- a/docs/contributing/code.md +++ /dev/null @@ -1,139 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/code.md](../../packages/mermaid/src/docs/contributing/code.md). - -# Contributing Code - -Code it the heart of every software project. We strive to make it better. Who if not us? - -## Where is the Code Located? - -The core of Mermaid is located under `packages/mermaid/src`. - -## Running Mermaid Locally - -**Host** - -```bash -npx pnpm run dev -``` - -**Docker** - -```bash -./run dev -``` - -After starting the dev server open in your browser. - -Now you are ready to make your changes! - -## Make Changes - -Have a look at . 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 . -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!) - -Edit files in `packages/mermaid/src` as required. - -## 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). - -Just as important, the tests act as _specifications:_ they specify what the code does (or should do). -Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. - -If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. -(If there had been a test for the situation, the bug never would have happened in the first place.) -You may need to change existing tests if they were inaccurate. - -If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. - -### Unit Tests - -Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. - -Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) - -We use [Vitest](https://vitest.dev) to run unit tests. - -You can use the following command to run the unit tests: - -```sh -pnpm test -``` - -When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: - -```sh -pnpm test:watch -``` - -### Integration/End-to-End (e2e) tests - -These test the rendering and visual appearance of the diagrams. -This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! - -To start working with the e2e tests: - -1. Run `pnpm dev` to start the dev server -2. Start **Cypress** by running `pnpm cypress:open`. - -The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. - -When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. - -This is what a rendering test looks like: - -```js -it('should render forks and joins', () => { - imgSnapshotTest( - ` - stateDiagram - state fork_state <<fork>> - [*] --> fork_state - fork_state --> State2 - fork_state --> State3 - - state join_state <<join>> - State2 --> join_state - State3 --> join_state - join_state --> State4 - State4 --> [*] - `, - { logLevel: 0 } - ); - cy.get('svg'); -}); -``` - - - - - -## 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. - -The documentation has to be updated to users know that things have changed and added! -If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. - -eg: `# Feature Name (v+)` - -We know it can sometimes be hard to code _and_ write user documentation. - -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!) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 595fccf0ac..16832391ce 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -25,13 +25,11 @@ flowchart LR ### Get the Source Code -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. +In GitHub, you first [**fork a mermaid repository**](https://github.com/mermaid-js/mermaid/fork) 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). +> **💡 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 git@github.com/your-fork/mermaid @@ -228,7 +226,7 @@ If your work is specific to a single diagram type, it is a good idea to put the Code it the heart of every software project. We strive to make it better. Who if not us? -### Where is the code located? +### Where is the Code Located? The core of Mermaid is located under `packages/mermaid/src`. @@ -263,8 +261,7 @@ Edit files in `packages/mermaid/src` as required. ### 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). +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). Just as important, the tests act as _specifications:_ they specify what the code does (or should do). Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. @@ -283,6 +280,8 @@ Unit tests are mandatory all code except the renderers. (The renderers are teste We use [Vitest](https://vitest.dev) to run unit tests. +**Host** + You can use the following command to run the unit tests: ```sh @@ -295,6 +294,14 @@ When writing new tests, it's easier to have the tests automatically run as you m pnpm test:watch ``` +**Docker** + +When using Docker prepend your command with `./run`: + +```sh +./run pnpm test +``` + #### Integration/End-to-End (e2e) tests These test the rendering and visual appearance of the diagrams. @@ -302,8 +309,16 @@ This ensures that the rendering of that feature in the e2e will be reviewed in t To start working with the e2e tests: -1. Run `pnpm dev` to start the dev server -2. Start **Cypress** by running `pnpm cypress:open`. +**Host** + +- Run `pnpm dev` to start the dev server +- Start **Cypress** by running `pnpm cypress:open`. + +**Docker** + +- Enable local connections for x11 server `xhost +local:` +- Run `./run pnpm dev` to start the dev server +- Start **Cypress** by running `./run pnpm cypress:open --project .`. The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. @@ -470,7 +485,7 @@ If you want to propose changes to how the documentation is _organized_, such as > Do not forget to push your changes > > ```bash -> git push -u origin docs/2910_update-contributing-guidelines +> git push -u origin docs/2910_update-guidelines > ``` We make all changes via Pull Requests (PRs). Open a new one. @@ -492,4 +507,4 @@ You have successfully submitted your improvements! What is next? - 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. +Thanks for you help! diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md deleted file mode 100644 index 550adc6d3a..0000000000 --- a/docs/contributing/documentation.md +++ /dev/null @@ -1,99 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/documentation.md](../../packages/mermaid/src/docs/contributing/documentation.md). - -# 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? - -## Where is the Documentation Located? - -> **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. - -Documentation 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-example -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"] -``` - -```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"] -``` - -## Enable Github Actions - -> **Warning** -> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first - -## Running the Documentation Website Locally - -**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** - -Start development server for the documentation site - -**Host** - -```bash -pnpm --filter mermaid run docs:dev -``` - -or - -```bash -cd packages/mermaid -pnpm docs:dev -``` - -**Docker** - -```bash -./run docs:dev -``` - -Open in your browser. - -## Format - -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. - -> **‼️ Danger** -> Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly. - -````markdown -```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). diff --git a/docs/contributing/intro.md b/docs/contributing/intro.md index c7759b60d1..9297c7d5f3 100644 --- a/docs/contributing/intro.md +++ b/docs/contributing/intro.md @@ -4,7 +4,7 @@ > > ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/intro.md](../../packages/mermaid/src/docs/contributing/intro.md). -# Contributing to Mermaid +# Getting Started So you want to help? That's great! @@ -31,22 +31,25 @@ 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). +> **💡 Tip** > **Check out our** [**detailed contribution guide**](./contributing.md). - +Where to start: - +- You could start getting some knowledge of the code base by working on [these "good first issues"](https://github.com/mermaid-js/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22+). +- You could jump right in and help us fix any of [these bugs](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug+%2F+Error%22++label%3A%22Contributor+needed%22+)! +- You could help write and [improve the documentation](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). +- You could work on a new feature! [These](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22+) are some ideas! +- You could confirm the bugs in [these issues](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Status%3A+Triage%22++label%3A%22Type%3A+Bug+%2F+Error%22). -## Where do I start? +[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) -- 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+). -- You could jump right in and help us fix any of [these bugs](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%22Help+wanted%21%22+label%3A%22Area%3A+Development%22)! -- You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! -- [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +## A Question Or a Suggestion? + +> **💡 Tip** > **Have a look at** [**how to open an issue**](./questions-and-suggestions.md). + +If you have faced a vulnerability [report it to us](./security.md). ## Last Words diff --git a/docs/contributing/questions-and-suggestions.md b/docs/contributing/questions-and-suggestions.md index 5162886b8e..ebe85b4176 100644 --- a/docs/contributing/questions-and-suggestions.md +++ b/docs/contributing/questions-and-suggestions.md @@ -6,20 +6,20 @@ # Questions or Suggestions? -**_\[TODO: This section is still a WIP. It still needs MAJOR revision.]_** +## Search for Existing Issue -## First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. +First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. - [Search in Discussions](https://github.com/orgs/mermaid-js/discussions) - [Search in Issues (Open & Closed)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue) If you find an open issue or discussion thread that is similar to your question but isn't answered, you can let us know that you are also interested in it. -Use the GitHub reactions to add a thumbs-up to the issue or discussion thread. +Use the GitHub reactions to add a thumbs-up to the issue or discussion thread, or append to the issue if needed. This helps the team know the relative interest in something and helps them set priorities and assignments. -Feel free to add to the discussion on the issue or topic. +## Add a new Issue -If you can't find anything that already addresses your question or suggestion, _open a new issue:_ +You have not found anything that already addresses your request, or maybe you have come up with the new idea? Feel free to open a new issue or discussion. -Log in to [GitHub.com](https://www.github.com), open or append to an issue [using the GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). +Log in to [GitHub.com](https://www.github.com), and use [GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues). Press \[] issue, select the appropriate template and describe your problem. From a7d0d414b2a6025a65d6dda2fdca1a95f2e0da19 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Thu, 4 Jan 2024 03:56:45 +0300 Subject: [PATCH 16/39] Small reorganizing --- docs/community/contributing.md | 16 +++++++++------- .../mermaid/src/docs/community/contributing.md | 18 ++++++++++-------- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 5eb17ead95..0110e71458 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -312,13 +312,13 @@ To start working with the e2e tests: **Host** - Run `pnpm dev` to start the dev server -- Start **Cypress** by running `pnpm cypress:open`. +- Start **Cypress** by running `pnpm cypress:open` **Docker** - Enable local connections for x11 server `xhost +local:` - Run `./run pnpm dev` to start the dev server -- Start **Cypress** by running `./run pnpm cypress:open --project .`. +- Start **Cypress** by running `./run pnpm cypress:open --project .` The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. @@ -402,11 +402,6 @@ flowchart LR source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` -### Enable Github Actions - -> **Warning** -> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first - ### Running the Documentation Website Locally **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** @@ -479,6 +474,13 @@ This is a danger alert 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**. +### Build Docs + +The content of `/docs` folder is built with Github Actions. + +> **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** diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 71a4f4b2dc..5dcf012b88 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -313,13 +313,13 @@ To start working with the e2e tests: **Host** - Run `pnpm dev` to start the dev server -- Start **Cypress** by running `pnpm cypress:open`. +- Start **Cypress** by running `pnpm cypress:open` **Docker** - Enable local connections for x11 server `xhost +local:` - Run `./run pnpm dev` to start the dev server -- Start **Cypress** by running `./run pnpm cypress:open --project .`. +- Start **Cypress** by running `./run pnpm cypress:open --project .` The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. @@ -397,12 +397,6 @@ flowchart LR source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` -### Enable Github Actions - -```warning -So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first -``` - ### Running the Documentation Website Locally **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** @@ -480,6 +474,14 @@ This is a danger alert 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**. +### Build Docs + +The content of `/docs` folder is built with Github Actions. + +```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 From e2fd5ecd02014adea97e2f756e6dede2d19d1e2a Mon Sep 17 00:00:00 2001 From: nirname Date: Thu, 4 Jan 2024 01:00:15 +0000 Subject: [PATCH 17/39] Update docs --- docs/contributing/contributing.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 16832391ce..90048ba03d 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -312,13 +312,13 @@ To start working with the e2e tests: **Host** - Run `pnpm dev` to start the dev server -- Start **Cypress** by running `pnpm cypress:open`. +- Start **Cypress** by running `pnpm cypress:open` **Docker** - Enable local connections for x11 server `xhost +local:` - Run `./run pnpm dev` to start the dev server -- Start **Cypress** by running `./run pnpm cypress:open --project .`. +- Start **Cypress** by running `./run pnpm cypress:open --project .` The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. @@ -402,11 +402,6 @@ flowchart LR source["Edit /packages/mermaid/src/docs"] -- automatic processing--> published["View /docs which will be publised on Official Website"] ``` -### Enable Github Actions - -> **Warning** -> So as to allow automatic compilation of documentation pages you have to enable github actions on your fork first - ### Running the Documentation Website Locally **[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** @@ -479,6 +474,13 @@ This is a danger alert 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**. +### Build Docs + +The content of `/docs` folder is built with Github Actions. + +> **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** From e7824f05cb885d8e67c14b01c34118ccbf87ef0f Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Thu, 4 Jan 2024 04:07:21 +0300 Subject: [PATCH 18/39] Fixes for tutorials link --- README.md | 4 ++-- README.zh-CN.md | 4 ++-- packages/mermaid/src/docs/intro/getting-started.md | 2 +- packages/mermaid/src/docs/intro/index.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cf21fdb8e6..5acafa95d1 100644 --- a/README.md +++ b/README.md @@ -74,12 +74,12 @@ Mermaid addresses this problem by enabling users to create easily modifiable dia
Mermaid allows even non-programmers to easily create detailed diagrams through the [Mermaid Live Editor](https://mermaid.live/).
-For video tutorials, visit our [Tutorials](./docs/config/Tutorials.md) page. +For video tutorials, visit our [Tutorials](./docs/ecosystem/tutorials.md) page. Use Mermaid with your favorite applications, check out the list of [Integrations and Usages of Mermaid](./docs/ecosystem/integrations-community.md). You can also use Mermaid within [GitHub](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) as well many of your other favorite applications—check out the list of [Integrations and Usages of Mermaid](./docs/ecosystem/integrations-community.md). -For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](./docs/intro/getting-started.md), [Usage](./docs/config/usage.md) and [Tutorials](./docs/config/Tutorials.md). +For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](./docs/intro/getting-started.md), [Usage](./docs/config/usage.md) and [Tutorials](./docs/ecosystem/tutorials.md). In our release process we rely heavily on visual regression tests using [applitools](https://applitools.com/). Applitools is a great service which has been easy to use and integrate with our tests. diff --git a/README.zh-CN.md b/README.zh-CN.md index 98975ea331..23c9bc722e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -57,9 +57,9 @@ Mermaid 是一个基于 Javascript 的图表绘制工具，通过解析类 Markd Mermaid 通过允许用户创建便于修改的图表来解决这一难题，它也可以作为生产脚本（或其他代码）的一部分。

Mermaid 甚至能让非程序员也能通过 [Mermaid Live Editor](https://mermaid.live/) 轻松创建详细的图表。
-你可以访问 [教程](./docs/config/Tutorials.md) 来查看 Live Editor 的视频教程，也可以查看 [Mermaid 的集成和使用](./docs/ecosystem/integrations-community.md) 这个清单来检查你的文档工具是否已经集成了 Mermaid 支持。 +你可以访问 [教程](./docs/ecosystem/tutorials.md) 来查看 Live Editor 的视频教程，也可以查看 [Mermaid 的集成和使用](./docs/ecosystem/integrations-community.md) 这个清单来检查你的文档工具是否已经集成了 Mermaid 支持。 -如果想要查看关于 Mermaid 更详细的介绍及基础使用方式，可以查看 [入门指引](./docs/intro/getting-started.md), [用法](./docs/config/usage.md) 和 [教程](./docs/config/Tutorials.md). +如果想要查看关于 Mermaid 更详细的介绍及基础使用方式，可以查看 [入门指引](./docs/intro/getting-started.md), [用法](./docs/config/usage.md) 和 [教程](./docs/ecosystem/tutorials.md). diff --git a/packages/mermaid/src/docs/intro/getting-started.md b/packages/mermaid/src/docs/intro/getting-started.md index 7603906c1b..6318fbe81c 100644 --- a/packages/mermaid/src/docs/intro/getting-started.md +++ b/packages/mermaid/src/docs/intro/getting-started.md @@ -6,7 +6,7 @@ This section talks about the different ways to deploy Mermaid. Learning the [Syn > Generally the live editor is enough for most general uses of mermaid, and is a good place to start learning. -**Absolute beginners are advised to view the Video [Tutorials](../config/Tutorials.md) on the Live Editor, to gain a better understanding of mermaid.** +**Absolute beginners are advised to view the Video [Tutorials](../ecosystem/tutorials.md) on the Live Editor, to gain a better understanding of mermaid.** ## Four ways of using mermaid: diff --git a/packages/mermaid/src/docs/intro/index.md b/packages/mermaid/src/docs/intro/index.md index 535ee3a3dc..c159ec6878 100644 --- a/packages/mermaid/src/docs/intro/index.md +++ b/packages/mermaid/src/docs/intro/index.md @@ -36,7 +36,7 @@ But not having diagrams or docs ruins productivity and hurts organizational lear Mermaid addresses this problem by enabling users to create easily modifiable diagrams, it can also be made part of production scripts (and other pieces of code).

Mermaid allows even non-programmers to easily create detailed and diagrams through the [Mermaid Live Editor](https://mermaid.live/).
-[Tutorials](../config/Tutorials.md) has video tutorials. +[Tutorials](../ecosystem/tutorials.md) has video tutorials. Use Mermaid with your favorite applications, check out the list of [Community Integrations](../ecosystem/integrations-community.md). From a32e72b660af3acfb37bfe5f510a23f7df1adb8c Mon Sep 17 00:00:00 2001 From: nirname Date: Thu, 4 Jan 2024 01:12:59 +0000 Subject: [PATCH 19/39] Update docs --- docs/intro/getting-started.md | 2 +- docs/intro/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/intro/getting-started.md b/docs/intro/getting-started.md index 95d7b594e0..061e625d77 100644 --- a/docs/intro/getting-started.md +++ b/docs/intro/getting-started.md @@ -12,7 +12,7 @@ This section talks about the different ways to deploy Mermaid. Learning the [Syn > Generally the live editor is enough for most general uses of mermaid, and is a good place to start learning. -**Absolute beginners are advised to view the Video [Tutorials](../config/Tutorials.md) on the Live Editor, to gain a better understanding of mermaid.** +**Absolute beginners are advised to view the Video [Tutorials](../ecosystem/tutorials.md) on the Live Editor, to gain a better understanding of mermaid.** ## Four ways of using mermaid: diff --git a/docs/intro/index.md b/docs/intro/index.md index 5a77fa5874..3c5cae7573 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -41,7 +41,7 @@ Diagramming and documentation costs precious developer time and gets outdated qu But not having diagrams or docs ruins productivity and hurts organizational learning.
Mermaid addresses this problem by enabling users to create easily modifiable diagrams, it can also be made part of production scripts (and other pieces of code).

Mermaid allows even non-programmers to easily create detailed and diagrams through the [Mermaid Live Editor](https://mermaid.live/).
-[Tutorials](../config/Tutorials.md) has video tutorials. +[Tutorials](../ecosystem/tutorials.md) has video tutorials. Use Mermaid with your favorite applications, check out the list of [Community Integrations](../ecosystem/integrations-community.md). From 67dde70bec080c7c6f2e9f05bca03cf3693cc446 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 16:36:12 +0300 Subject: [PATCH 20/39] Fixes --- .../img/python-mermaid-integration.png | Bin 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/mermaid/src/docs/{config => ecosystem}/img/python-mermaid-integration.png (100%) diff --git a/packages/mermaid/src/docs/config/img/python-mermaid-integration.png b/packages/mermaid/src/docs/ecosystem/img/python-mermaid-integration.png similarity index 100% rename from packages/mermaid/src/docs/config/img/python-mermaid-integration.png rename to packages/mermaid/src/docs/ecosystem/img/python-mermaid-integration.png From 9aaf63139adf1f748c61a3d4232132720e31cd94 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 16:53:31 +0300 Subject: [PATCH 21/39] Removed unused files --- docs/contributing/contributing.md | 2 +- packages/mermaid/src/docs/community/setup.md | 110 --------------- .../mermaid/src/docs/community/workflow.md | 126 ------------------ packages/mermaid/src/docs/config/usage.md | 2 +- 4 files changed, 2 insertions(+), 238 deletions(-) delete mode 100644 packages/mermaid/src/docs/community/setup.md delete mode 100644 packages/mermaid/src/docs/community/workflow.md diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 90048ba03d..f63f71f5f3 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -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. diff --git a/packages/mermaid/src/docs/community/setup.md b/packages/mermaid/src/docs/community/setup.md deleted file mode 100644 index 6a637cc4fd..0000000000 --- a/packages/mermaid/src/docs/community/setup.md +++ /dev/null @@ -1,110 +0,0 @@ -# Initial Setup - -Initial setup consists of 3 main steps: - -```mermaid-nocode -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.) diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md deleted file mode 100644 index 5783125f9b..0000000000 --- a/packages/mermaid/src/docs/community/workflow.md +++ /dev/null @@ -1,126 +0,0 @@ -# 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-nocode - 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-nocode -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 # -``` - -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. diff --git a/packages/mermaid/src/docs/config/usage.md b/packages/mermaid/src/docs/config/usage.md index ae3ad0f0aa..67ed9c0676 100644 --- a/packages/mermaid/src/docs/config/usage.md +++ b/packages/mermaid/src/docs/config/usage.md @@ -14,7 +14,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 From 9ccb340d63379413a2bae640b9334be6687e5f59 Mon Sep 17 00:00:00 2001 From: nirname Date: Fri, 5 Jan 2024 13:56:36 +0000 Subject: [PATCH 22/39] Update docs --- docs/community/setup.md | 115 ---------------- docs/community/workflow.md | 128 ------------------ docs/config/usage.md | 2 +- docs/contributing/contributing.md | 2 +- docs/contributing/setup.md | 115 ---------------- docs/contributing/workflow.md | 128 ------------------ .../img/python-mermaid-integration.png | Bin 7 files changed, 2 insertions(+), 488 deletions(-) delete mode 100644 docs/community/setup.md delete mode 100644 docs/community/workflow.md delete mode 100644 docs/contributing/setup.md delete mode 100644 docs/contributing/workflow.md rename docs/{config => ecosystem}/img/python-mermaid-integration.png (100%) diff --git a/docs/community/setup.md b/docs/community/setup.md deleted file mode 100644 index 33c13519d0..0000000000 --- a/docs/community/setup.md +++ /dev/null @@ -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.) diff --git a/docs/community/workflow.md b/docs/community/workflow.md deleted file mode 100644 index 2ccc36e050..0000000000 --- a/docs/community/workflow.md +++ /dev/null @@ -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`]\(() 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 # -``` - -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. diff --git a/docs/config/usage.md b/docs/config/usage.md index 8bd34345f1..7c3bc2675a 100644 --- a/docs/config/usage.md +++ b/docs/config/usage.md @@ -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 diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index f63f71f5f3..90048ba03d 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -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. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md deleted file mode 100644 index 952eb8b692..0000000000 --- a/docs/contributing/setup.md +++ /dev/null @@ -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.) diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md deleted file mode 100644 index f31cc8afab..0000000000 --- a/docs/contributing/workflow.md +++ /dev/null @@ -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`]\(() 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 # -``` - -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. diff --git a/docs/config/img/python-mermaid-integration.png b/docs/ecosystem/img/python-mermaid-integration.png similarity index 100% rename from docs/config/img/python-mermaid-integration.png rename to docs/ecosystem/img/python-mermaid-integration.png From 3c27f46c5708740902d0bcb5a96cf9fba7e33e5f Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 17:13:45 +0300 Subject: [PATCH 23/39] Fixed dead links --- packages/mermaid/src/docs/community/contributing.md | 2 +- packages/mermaid/src/docs/config/usage.md | 2 +- packages/mermaid/src/docs/intro/getting-started.md | 2 +- packages/mermaid/src/docs/intro/index.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 5dcf012b88..5a54b87570 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -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](#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. diff --git a/packages/mermaid/src/docs/config/usage.md b/packages/mermaid/src/docs/config/usage.md index 67ed9c0676..5019611a73 100644 --- a/packages/mermaid/src/docs/config/usage.md +++ b/packages/mermaid/src/docs/config/usage.md @@ -14,7 +14,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](../comminuty/tutorials.md) on how to use the Mermaid Live Editor. +We have compiled some Video [Tutorials](../ecosystem/tutorials.md) on how to use the Mermaid Live Editor. ### Installing and Hosting Mermaid on a Webpage diff --git a/packages/mermaid/src/docs/intro/getting-started.md b/packages/mermaid/src/docs/intro/getting-started.md index 6318fbe81c..3d29e42316 100644 --- a/packages/mermaid/src/docs/intro/getting-started.md +++ b/packages/mermaid/src/docs/intro/getting-started.md @@ -36,7 +36,7 @@ graph TD In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it. -The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. An easy introduction to mermaid configuration is found in the [Advanced usage](../config/advanced.md) section. A complete configuration reference cataloging the default values can be found on the [mermaidAPI](../config/setup/README.md) page. +The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. A complete configuration reference cataloging the default values can be found on the [mermaidAPI](../config/setup/README.md) page. ![Code,Config and Preview](./img/Code-Preview-Config.png) diff --git a/packages/mermaid/src/docs/intro/index.md b/packages/mermaid/src/docs/intro/index.md index c159ec6878..2a7ef13ba0 100644 --- a/packages/mermaid/src/docs/intro/index.md +++ b/packages/mermaid/src/docs/intro/index.md @@ -42,7 +42,7 @@ Use Mermaid with your favorite applications, check out the list of [Community In For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](../intro/getting-started.md) and [Usage](../config/usage.md). -🌐 [CDN](https://www.jsdelivr.com/package/npm/mermaid) | 📖 [Documentation](https://mermaidjs.github.io) | 🙌 [Contribution](../community/development.md) | 🔌 [Plug-Ins](../ecosystem/integrations-community.md) +🌐 [CDN](https://www.jsdelivr.com/package/npm/mermaid) | 📖 [Documentation](https://mermaidjs.github.io) | 🙌 [Contribution](../community/contributing.md) | 🔌 [Plug-Ins](../ecosystem/integrations-community.md) > 🖖 Keep a steady pulse: mermaid needs more Collaborators, [Read More](https://github.com/knsv/mermaid/issues/866). @@ -135,7 +135,7 @@ Don't hesitate to contact me if you want to get involved! Mermaid is a growing community and is always accepting new contributors. There's a lot of different ways to help out and we're always looking for extra hands! Look at [this issue](https://github.com/mermaid-js/mermaid/issues/866) if you want to know where to start helping out. -Detailed information about how to contribute can be found in the [contribution guideline](/community/development). +Detailed information about how to contribute can be found in the [contribution guideline](../community/contributing.md). ### Requirements From a05aba4cc98ef87dce239b952278b45aa73a0e09 Mon Sep 17 00:00:00 2001 From: nirname Date: Fri, 5 Jan 2024 14:19:54 +0000 Subject: [PATCH 24/39] Update docs --- docs/community/contributing.md | 2 +- docs/config/usage.md | 2 +- docs/contributing/contributing.md | 2 +- docs/intro/getting-started.md | 2 +- docs/intro/index.md | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 0110e71458..d61ab25c4a 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -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](#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. Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused. diff --git a/docs/config/usage.md b/docs/config/usage.md index 7c3bc2675a..6ef621f98f 100644 --- a/docs/config/usage.md +++ b/docs/config/usage.md @@ -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](../comminuty/tutorials.md) on how to use the Mermaid Live Editor. +We have compiled some Video [Tutorials](../ecosystem/tutorials.md) on how to use the Mermaid Live Editor. ### Installing and Hosting Mermaid on a Webpage diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 90048ba03d..a61f5311bf 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -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](#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. Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused. diff --git a/docs/intro/getting-started.md b/docs/intro/getting-started.md index 061e625d77..c1be9ccecd 100644 --- a/docs/intro/getting-started.md +++ b/docs/intro/getting-started.md @@ -53,7 +53,7 @@ graph TD In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it. -The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. An easy introduction to mermaid configuration is found in the [Advanced usage](../config/advanced.md) section. A complete configuration reference cataloging the default values can be found on the [mermaidAPI](../config/setup/README.md) page. +The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. A complete configuration reference cataloging the default values can be found on the [mermaidAPI](../config/setup/README.md) page. ![Code,Config and Preview](./img/Code-Preview-Config.png) diff --git a/docs/intro/index.md b/docs/intro/index.md index 3c5cae7573..79ef53b4b9 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -47,7 +47,7 @@ Use Mermaid with your favorite applications, check out the list of [Community In For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](../intro/getting-started.md) and [Usage](../config/usage.md). -🌐 [CDN](https://www.jsdelivr.com/package/npm/mermaid) | 📖 [Documentation](https://mermaidjs.github.io) | 🙌 [Contribution](../community/development.md) | 🔌 [Plug-Ins](../ecosystem/integrations-community.md) +🌐 [CDN](https://www.jsdelivr.com/package/npm/mermaid) | 📖 [Documentation](https://mermaidjs.github.io) | 🙌 [Contribution](../community/contributing.md) | 🔌 [Plug-Ins](../ecosystem/integrations-community.md) > 🖖 Keep a steady pulse: mermaid needs more Collaborators, [Read More](https://github.com/knsv/mermaid/issues/866). @@ -378,7 +378,7 @@ Don't hesitate to contact me if you want to get involved! Mermaid is a growing community and is always accepting new contributors. There's a lot of different ways to help out and we're always looking for extra hands! Look at [this issue](https://github.com/mermaid-js/mermaid/issues/866) if you want to know where to start helping out. -Detailed information about how to contribute can be found in the [contribution guideline](/community/development). +Detailed information about how to contribute can be found in the [contribution guideline](../community/contributing.md). ### Requirements From 17312a023243d2d197f167d8d4d54398c5312d06 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 17:37:34 +0300 Subject: [PATCH 25/39] Cleanup --- .github/pull_request_template.md | 2 +- contrib.md | 78 ------------------- .../mermaid/src/docs/.vitepress/config.ts | 4 +- packages/mermaid/src/docs/contributing | 1 - run | 2 +- 5 files changed, 4 insertions(+), 83 deletions(-) delete mode 100644 contrib.md delete mode 120000 packages/mermaid/src/docs/contributing diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4934163b55..f20204a714 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,5 +14,5 @@ Make sure you - [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md) - [ ] :computer: have added necessary unit/e2e tests. -- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/contribution/code.md#update-documentation) is used for all new features. +- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/contributing.md#update-documentation) is used for all new features. - [ ] :bookmark: targeted `develop` branch diff --git a/contrib.md b/contrib.md deleted file mode 100644 index 843e9e6224..0000000000 --- a/contrib.md +++ /dev/null @@ -1,78 +0,0 @@ -FIXME: remove before merge, this is previous contributing.md - -## 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 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 . - -#### 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) diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index c7d29b277f..710aa6b2d5 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -84,8 +84,8 @@ function nav() { }, { text: 'Contributing', - link: '/contributing/intro', - activeMatch: '/contributing/', + link: '/comminuty/intro', + activeMatch: '/comminuty/', }, { text: 'Latest News', diff --git a/packages/mermaid/src/docs/contributing b/packages/mermaid/src/docs/contributing deleted file mode 120000 index 013cf3ce01..0000000000 --- a/packages/mermaid/src/docs/contributing +++ /dev/null @@ -1 +0,0 @@ -community/ \ No newline at end of file diff --git a/run b/run index fbf4372631..aeaccb474f 100755 --- a/run +++ b/run @@ -50,7 +50,7 @@ Development quick start guide: $(bold ./$name pnpm install) # Install packages $(bold ./$name dev) # Run dev server with examples, open http://localhost:9000 -$(bold ./$name pnpm vitest) # Run watcher for unit tests +$(bold ./$name pnpm test) # Run watcher for unit tests $(bold ./$name cypress) # Run integration tests (after starting dev server) $(bold ./$name pnpm build) # Prepare it for production $(bold ./$name docs:dev) # Then add documentation, open http://localhost:3333 From e0bd6842489844fffae8bc1fe83652dee26b48c1 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 18:02:13 +0300 Subject: [PATCH 26/39] Removed duplicated docs, keep community folder name --- docs/contributing/contributing.md | 512 ------------------ docs/contributing/img/er.png | Bin 56576 -> 0 bytes docs/contributing/intro.md | 60 -- docs/contributing/new-diagram.md | 217 -------- .../contributing/questions-and-suggestions.md | 25 - docs/contributing/security.md | 29 - 6 files changed, 843 deletions(-) delete mode 100644 docs/contributing/contributing.md delete mode 100644 docs/contributing/img/er.png delete mode 100644 docs/contributing/intro.md delete mode 100644 docs/contributing/new-diagram.md delete mode 100644 docs/contributing/questions-and-suggestions.md delete mode 100644 docs/contributing/security.md diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md deleted file mode 100644 index a61f5311bf..0000000000 --- a/docs/contributing/contributing.md +++ /dev/null @@ -1,512 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/contributing.md](../../packages/mermaid/src/docs/contributing/contributing.md). - -# Mermaid Contributing Guide - -You decided to take part in the development? Welcome! - -We were trying to make our guidelines for you as explicit and detailed as possible. - -## 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 mermaid repository**](https://github.com/mermaid-js/mermaid/fork) 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. - -> **💡 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 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. - -> **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. - -```mermaid ---- -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** -> 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` - -## Contributing Code - -Code it the heart of every software project. We strive to make it better. Who if not us? - -### Where is the Code Located? - -The core of Mermaid is located under `packages/mermaid/src`. - -### Running Mermaid Locally - -**Host** - -```bash -npx pnpm run dev -``` - -**Docker** - -```bash -./run dev -``` - -After starting the dev server open in your browser. - -Now you are ready to make your changes! - -### Make Changes - -Have a look at . 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 . -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!) - -Edit files in `packages/mermaid/src` as required. - -### 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). - -Just as important, the tests act as _specifications:_ they specify what the code does (or should do). -Whenever someone is new to a section of code, they should be able to read the tests to get a thorough understanding of what it does and why. - -If you are fixing a bug, you should add tests to ensure that your code has actually fixed the bug, to specify/describe what the code is doing, and to ensure the bug doesn't happen again. -(If there had been a test for the situation, the bug never would have happened in the first place.) -You may need to change existing tests if they were inaccurate. - -If you are adding a feature, you will definitely need to add tests. Depending on the size of your feature, you may need to add integration tests. - -#### Unit Tests - -Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. - -Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) - -We use [Vitest](https://vitest.dev) to run unit tests. - -**Host** - -You can use the following command to run the unit tests: - -```sh -pnpm test -``` - -When writing new tests, it's easier to have the tests automatically run as you make changes. You can do this by running the following command: - -```sh -pnpm test:watch -``` - -**Docker** - -When using Docker prepend your command with `./run`: - -```sh -./run pnpm test -``` - -#### Integration/End-to-End (e2e) tests - -These test the rendering and visual appearance of the diagrams. -This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! - -To start working with the e2e tests: - -**Host** - -- Run `pnpm dev` to start the dev server -- Start **Cypress** by running `pnpm cypress:open` - -**Docker** - -- Enable local connections for x11 server `xhost +local:` -- Run `./run pnpm dev` to start the dev server -- Start **Cypress** by running `./run pnpm cypress:open --project .` - -The rendering tests are very straightforward to create. There is a function `imgSnapshotTest`, which takes a diagram in text form and the mermaid options, and it renders that diagram in Cypress. - -When running in CI it will take a snapshot of the rendered diagram and compare it with the snapshot from last build and flag it for review if it differs. - -This is what a rendering test looks like: - -```js -it('should render forks and joins', () => { - imgSnapshotTest( - ` - stateDiagram - state fork_state <<fork>> - [*] --> fork_state - fork_state --> State2 - fork_state --> State3 - - state join_state <<join>> - State2 --> join_state - State3 --> join_state - join_state --> State4 - State4 --> [*] - `, - { logLevel: 0 } - ); - cy.get('svg'); -}); -``` - - - - - -### Update Documentation - -> **💡 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. -Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused. - -The documentation has to be updated to users know that things have changed and added! -If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. - -eg: `# Feature Name (v+)` - -We know it can sometimes be hard to code _and_ write user documentation. - -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!) - -## 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? - -### Where is the Documentation Located? - -> **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. - -Documentation 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-example -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"] -``` - -```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"] -``` - -### Running the Documentation Website Locally - -**[The mermaid documentation site](https://mermaid.js.org/) is powered by [Vitepress](https://vitepress.vuejs.org/).** - -Start development server for the documentation site - -**Host** - -```bash -pnpm --filter mermaid run docs:dev -``` - -or - -```bash -cd packages/mermaid -pnpm docs:dev -``` - -**Docker** - -```bash -./run docs:dev -``` - -Open in your browser. - -### 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). - -You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a note, tip, warning or danger box. - -> **‼️ 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 -``` - -```tip -This is a tip -``` - -```warning -This is a warning -``` - -```danger -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**, which is defined in [the vitepress config](../.vitepress/config.ts). The same goes to **topbar**. - -### Build Docs - -The content of `/docs` folder is built with Github Actions. - -> **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** -> Do not forget to push your changes -> -> ```bash -> git push -u origin docs/2910_update-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 # -``` - -## 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. - -Thanks for you help! diff --git a/docs/contributing/img/er.png b/docs/contributing/img/er.png deleted file mode 100644 index 21c44c257a3e0ee3e782dd5b6696602f6d9f5172..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 56576 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 **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/intro.md](../../packages/mermaid/src/docs/contributing/intro.md). - -# Getting Started - -So you want to help? That's great! - -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) - -Here are a few things to get you started on the right path. - -## How can I help? - -```mermaid -mindmap - root)Contributing( - Development - Solving issues - Adding new diagrams - Handling pull requests - Updating tooling - Testing - Verification of fixed issues - Regression testing in connection with releases - Testing pull requests - Management - Coordinating the work - Classification and monitoring of incoming issues -``` - -## Join the Development - -> **💡 Tip** > **Check out our** [**detailed contribution guide**](./contributing.md). - -Where to start: - -- You could start getting some knowledge of the code base by working on [these "good first issues"](https://github.com/mermaid-js/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22+). -- You could jump right in and help us fix any of [these bugs](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug+%2F+Error%22++label%3A%22Contributor+needed%22+)! -- You could help write and [improve the documentation](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Documentation%22). -- You could work on a new feature! [These](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22+) are some ideas! -- You could confirm the bugs in [these issues](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Status%3A+Triage%22++label%3A%22Type%3A+Bug+%2F+Error%22). - -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -## A Question Or a Suggestion? - -> **💡 Tip** > **Have a look at** [**how to open an issue**](./questions-and-suggestions.md). - -If you have faced a vulnerability [report it to us](./security.md). - -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/contributing/new-diagram.md b/docs/contributing/new-diagram.md deleted file mode 100644 index 3f9f5f98ee..0000000000 --- a/docs/contributing/new-diagram.md +++ /dev/null @@ -1,217 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/new-diagram.md](../../packages/mermaid/src/docs/contributing/new-diagram.md). - -# Adding a New Diagram/Chart 📊 - -### Step 1: Grammar & Parsing - -#### Grammar - -This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2. - -For instance: - -- the flowchart starts with the keyword _graph_ -- the sequence diagram starts with the keyword _sequenceDiagram_ - -#### Store data found during parsing - -There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data. - -```jison -statement - : 'participant' actor { $$='actor'; } - | signal { $$='signal'; } - | note_statement { $$='note'; } - | 'title' message { yy.setTitle($2); } - ; -``` - -In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered. - -> **Note** -> Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user. - -For more info look at the example diagram type: - -The `yy` object has the following function: - -```javascript -exports.parseError = function (err, hash) { - mermaid.parseError(err, hash); -}; -``` - -when parsing the `yy` object is initialized as per below: - -```javascript -const parser = exampleParser.parser; -parser.yy = db; -``` - -### Step 2: Rendering - -Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequenceRenderer.js rather than the flowchart renderer as this is a more generic example. - -Place the renderer in the diagram folder. - -### Step 3: Detection of the new diagram type - -The second thing to do is to add the capability to detect the new diagram to type to the detectType in `diagram-api/detectType.ts`. The detection should return a key for the new diagram type. -[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type. -For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader -would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram. - -Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same. - -### Step 4: The final piece - triggering the rendering - -At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument. - -## Usage of the parser as a separate module - -### Setup - -```javascript -const graph = require('./graphDb'); -const flow = require('./parser/flow'); -flow.parser.yy = graph; -``` - -### Parsing - -```javascript -flow.parser.parse(text); -``` - -### Data extraction - -```javascript -graph.getDirection(); -graph.getVertices(); -graph.getEdges(); -``` - -The parser is also exposed in the mermaid api by calling: - -```javascript -const parser = mermaid.getParser(); -``` - -Note that the parse needs a graph object to store the data as per: - -```javascript -flow.parser.yy = graph; -``` - -Look at `graphDb.js` for more details on that object. - -## Layout - -If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from. - -### Common parts of a diagram - -There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are: - -- Directives, a way of modifying the diagram configuration from within the diagram code. -- Accessibility, a way for an author to provide additional information like titles and descriptions to people accessing a text with diagrams using a screen reader. -- Themes, there is a common way to modify the styling of diagrams in Mermaid. -- Comments should follow mermaid standards - -Here are some pointers on how to handle these different areas. - -## Accessibility - -Mermaid automatically adds the following accessibility information for the diagram SVG HTML element: - -- aria-roledescription -- accessible title -- accessible description - -### aria-roledescription - -The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element. - -See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) in [the Accessible Rich Internet Applications W3 standard.](https://www.w3.org/WAI/standards-guidelines/aria/) - -### accessible title and description - -The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md) - -As a design goal, the jison syntax should be similar between the diagrams. - -```jison - -* lexical grammar */ -%lex -%x acc_title -%x acc_descr -%x acc_descr_multiline - -%% -accTitle\s*":"\s* { this.begin("acc_title");return 'acc_title'; } -(?!\n|;|#)*[^\n]* { this.popState(); return "acc_title_value"; } -accDescr\s*":"\s* { this.begin("acc_descr");return 'acc_descr'; } -(?!\n|;|#)*[^\n]* { this.popState(); return "acc_descr_value"; } -accDescr\s*"{"\s* { this.begin("acc_descr_multiline");} -[\}] { this.popState(); } -[^\}]* return "acc_descr_multiline_value"; - -statement - : acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); } - | acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); } - | acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); } - -``` - -The functions for setting title and description are provided by a common module. This is the import from flowDb.js: - - import { - setAccTitle, - getAccTitle, - getAccDescription, - setAccDescription, - clear as commonClear, - } from '../../commonDb'; - -The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI. - -## Theming - -Mermaid supports themes and has an integrated theming engine. You can read more about how the themes can be used [in the docs](../config/theming.md). - -When adding themes to a diagram it comes down to a few important locations in the code. - -The entry point for the styling engine is in **src/styles.js**. The getStyles function will be called by Mermaid when the styles are being applied to the diagram. - -This function will in turn call a function _your diagram should provide_ returning the css for the new diagram. The diagram specific, also which is commonly also called getStyles and located in the folder for your diagram under src/diagrams and should be named styles.js. The getStyles function will be called with the theme options as an argument like in the following example: - -```js -const getStyles = (options) => - ` - .line { - stroke-width: 1; - stroke: ${options.lineColor}; - stroke-dasharray: 2; - } - // ... - `; -``` - -Note that you need to provide your function to the main getStyles by adding it into the themes object in **src/styles.js** like in the xyzDiagram in the provided example: - -```js -const themes = { - flowchart, - 'flowchart-v2': flowchart, - sequence, - xyzDiagram, - //... -}; -``` - -The actual options and values for the colors are defined in **src/theme/theme-\[xyz].js**. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups. diff --git a/docs/contributing/questions-and-suggestions.md b/docs/contributing/questions-and-suggestions.md deleted file mode 100644 index ebe85b4176..0000000000 --- a/docs/contributing/questions-and-suggestions.md +++ /dev/null @@ -1,25 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/questions-and-suggestions.md](../../packages/mermaid/src/docs/contributing/questions-and-suggestions.md). - -# Questions or Suggestions? - -## Search for Existing Issue - -First search to see if someone has already asked (and hopefully been answered) or suggested the same thing. - -- [Search in Discussions](https://github.com/orgs/mermaid-js/discussions) -- [Search in Issues (Open & Closed)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue) - -If you find an open issue or discussion thread that is similar to your question but isn't answered, you can let us know that you are also interested in it. -Use the GitHub reactions to add a thumbs-up to the issue or discussion thread, or append to the issue if needed. - -This helps the team know the relative interest in something and helps them set priorities and assignments. - -## Add a new Issue - -You have not found anything that already addresses your request, or maybe you have come up with the new idea? Feel free to open a new issue or discussion. - -Log in to [GitHub.com](https://www.github.com), and use [GitHub issue tracker of the mermaid-js repository](https://github.com/mermaid-js/mermaid/issues). Press \[] issue, select the appropriate template and describe your problem. diff --git a/docs/contributing/security.md b/docs/contributing/security.md deleted file mode 100644 index a8ab8e7078..0000000000 --- a/docs/contributing/security.md +++ /dev/null @@ -1,29 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/security.md](../../packages/mermaid/src/docs/contributing/security.md). - -# Security - -The Mermaid team takes the security of Mermaid and the applications that use Mermaid seriously. This page describes how to report any vulnerabilities you may find, and lists best practices to minimize the risk of introducing a vulnerability. - -## Reporting vulnerabilities - -To report a vulnerability, please e-mail with a description of the issue, the steps you took to create the issue, affected versions, and if known, mitigations for the issue. - -We aim to reply within three working days, probably much sooner. - -You should expect a close collaboration as we work to resolve the issue you have reported. Please reach out to again if you do not receive prompt attention and regular updates. - -You may also reach out to the team via our public Slack chat channels; however, please make sure to e-mail when reporting an issue, and avoid revealing information about vulnerabilities in public as that could that could put users at risk. - -## Best practices - -Keep current with the latest Mermaid releases. We regularly update Mermaid, and these updates may fix security defects discovered in previous versions. Check the Mermaid release notes for security-related updates. - -Keep your application’s dependencies up to date. Make sure you upgrade your package dependencies to keep the dependencies up to date. Avoid pinning to specific versions for your dependencies and, if you do, make sure you check periodically to see if your dependencies have had security updates, and update the pin accordingly. - -## Configuring DomPurify - -By default Mermaid uses a baseline [DOMPurify](https://github.com/cure53/DOMPurify) config. It is possible to override the options passed to DOMPurify by adding a `dompurifyConfig` key to the Mermaid options. This could potentially break the output of Mermaid so use this with caution. From 6d5f33856c25d27d80bafb21411d8449e171588f Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 19:33:15 +0300 Subject: [PATCH 27/39] Fixed redirects --- docs/community/contributing.md | 4 ++-- packages/mermaid/src/docs/.vitepress/config.ts | 14 +++++++------- .../src/docs/.vitepress/theme/redirect.spec.ts | 5 +++++ .../mermaid/src/docs/.vitepress/theme/redirect.ts | 15 ++++++++++----- .../mermaid/src/docs/community/contributing.md | 2 +- 5 files changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index d61ab25c4a..614e0599f4 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -8,7 +8,7 @@ You decided to take part in the development? Welcome! -We were trying to make our guidelines for you as explicit and detailed as possible. +We are trying to make our guidelines for you as explicit and detailed as possible. ## Initial Setup @@ -111,7 +111,7 @@ pnpm test **Docker** ```bash -./run pnpm test +./run pnpm vitest ``` The `test` script and others are in the top-level `package.json` file. diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index 710aa6b2d5..5a25098207 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -84,8 +84,8 @@ function nav() { }, { text: 'Contributing', - link: '/comminuty/intro', - activeMatch: '/comminuty/', + link: '/community/intro', + activeMatch: '/community/', }, { text: 'Latest News', @@ -200,11 +200,11 @@ function sidebarCommunity() { text: '🙌 Contributing', collapsed: false, items: [ - { text: 'Getting Started', link: '/contributing/intro' }, - { text: 'Contributing to Mermaid', link: '/contributing/contributing' }, - { text: 'Adding Diagrams', link: '/contributing/new-diagram' }, - { text: 'Questions and Suggestions', link: '/contributing/questions-and-suggestions' }, - { text: 'Security', link: '/contributing/security' }, + { text: 'Getting Started', link: '/community/intro' }, + { text: 'Contributing to Mermaid', link: '/community/contributing' }, + { text: 'Adding Diagrams', link: '/community/new-diagram' }, + { text: 'Questions and Suggestions', link: '/community/questions-and-suggestions' }, + { text: 'Security', link: '/community/security' }, ], }, ]; diff --git a/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts b/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts index 09c14d935b..9455882c52 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts +++ b/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts @@ -38,6 +38,11 @@ test.each([ ['https://mermaid.js.org/#/flowchart.md', 'syntax/flowchart.html'], // New docs, without base path, new domain ['https://mermaid.js.org/misc/faq.html', 'configure/faq.html'], + ['https://mermaid.js.org/community/newDiagram.html', 'community/new-diagram.html'], + ['https://mermaid.js.org/community/development.html', 'community/contributing.html#initial-setup'], + ['https://mermaid.js.org/community/docker-development.html', 'community/contributing.html#initial-setup'], + ['https://mermaid.js.org/community/code.html', 'community/contributing.html#contributing-code'], + ['https://mermaid.js.org/community/documentation.html', 'community/contributing.html#contributing-documentation'], [ 'https://mermaid.js.org/misc/faq.html#frequently-asked-questions', 'configure/faq.html#frequently-asked-questions', diff --git a/packages/mermaid/src/docs/.vitepress/theme/redirect.ts b/packages/mermaid/src/docs/.vitepress/theme/redirect.ts index e24d2beb9d..57cac68005 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/redirect.ts +++ b/packages/mermaid/src/docs/.vitepress/theme/redirect.ts @@ -58,7 +58,7 @@ const idRedirectMap: Record = { 'n00b-gettingstarted': 'intro/getting-started', 'n00b-overview': 'intro/getting-started', 'n00b-syntaxreference': 'intro/syntax-reference', - newdiagram: 'community/newDiagram', + newdiagram: 'community/new-diagram', pie: 'syntax/pie', plugins: '', quickstart: 'intro/getting-started', @@ -88,10 +88,15 @@ const urlRedirectMap: Record = { '/syntax/c4c.html': 'syntax/c4.html', '/ecosystem/integrations.html': 'ecosystem/integrations-community.html', '/ecosystem/showcases.html': 'ecosystem/integrations-create', - '/config/n00b-advanced.html': 'config/advanced', - '/intro/n00b-gettingStarted.html': 'intro/getting-started', - '/intro/n00b-syntaxReference.html': 'intro/syntax-reference', - '/community/n00b-overview.html': 'intro/getting-started', + '/config/n00b-advanced.html': 'config/configuration.html', + '/intro/n00b-gettingStarted.html': 'intro/getting-started.html', + '/intro/n00b-syntaxReference.html': 'intro/syntax-reference.html', + '/community/n00b-overview.html': 'intro/getting-started.html', + '/community/newDiagram.html': 'community/new-diagram.html', + '/community/development.html': 'community/contributing.html#initial-setup', + '/community/docker-development.html': 'community/contributing.html#initial-setup', + '/community/code.html': 'community/contributing.html#contributing-code', + '/community/documentation.html': 'community/contributing.html#contributing-documentation', }; /** diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 5a54b87570..695736cc9b 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -2,7 +2,7 @@ You decided to take part in the development? Welcome! -We were trying to make our guidelines for you as explicit and detailed as possible. +We are trying to make our guidelines for you as explicit and detailed as possible. ## Initial Setup From 5f9b965be38d34c1f2f52c6da971fbc49ac80c10 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 21:05:10 +0300 Subject: [PATCH 28/39] Linters --- .../src/docs/.vitepress/theme/redirect.spec.ts | 15 ++++++++++++--- run | 5 ++++- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts b/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts index 9455882c52..7a5481a59f 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts +++ b/packages/mermaid/src/docs/.vitepress/theme/redirect.spec.ts @@ -39,10 +39,19 @@ test.each([ // New docs, without base path, new domain ['https://mermaid.js.org/misc/faq.html', 'configure/faq.html'], ['https://mermaid.js.org/community/newDiagram.html', 'community/new-diagram.html'], - ['https://mermaid.js.org/community/development.html', 'community/contributing.html#initial-setup'], - ['https://mermaid.js.org/community/docker-development.html', 'community/contributing.html#initial-setup'], + [ + 'https://mermaid.js.org/community/development.html', + 'community/contributing.html#initial-setup', + ], + [ + 'https://mermaid.js.org/community/docker-development.html', + 'community/contributing.html#initial-setup', + ], ['https://mermaid.js.org/community/code.html', 'community/contributing.html#contributing-code'], - ['https://mermaid.js.org/community/documentation.html', 'community/contributing.html#contributing-documentation'], + [ + 'https://mermaid.js.org/community/documentation.html', + 'community/contributing.html#contributing-documentation', + ], [ 'https://mermaid.js.org/misc/faq.html#frequently-asked-questions', 'configure/faq.html#frequently-asked-questions', diff --git a/run b/run index aeaccb474f..920e346f83 100755 --- a/run +++ b/run @@ -50,7 +50,7 @@ Development quick start guide: $(bold ./$name pnpm install) # Install packages $(bold ./$name dev) # Run dev server with examples, open http://localhost:9000 -$(bold ./$name pnpm test) # Run watcher for unit tests +$(bold ./$name pnpm vitest) # Run watcher for unit tests $(bold ./$name cypress) # Run integration tests (after starting dev server) $(bold ./$name pnpm build) # Prepare it for production $(bold ./$name docs:dev) # Then add documentation, open http://localhost:3333 @@ -71,6 +71,9 @@ Examples of frequiently used commands: $(bold ./$name pnpm add --filter mermaid) $(underline package) Add package to mermaid +$(bold ./$name pnpm -w run lint:fix) + Run prettier and ES lint + $(bold git diff --name-only develop \| xargs ./$name pnpm prettier --write) Prettify everything you added so far From be7c6377caf3a56e70941bf0df0454492b3d434f Mon Sep 17 00:00:00 2001 From: nirname Date: Fri, 5 Jan 2024 18:08:31 +0000 Subject: [PATCH 29/39] Update docs --- docs/community/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 614e0599f4..ebf16cd3f0 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -111,7 +111,7 @@ pnpm test **Docker** ```bash -./run pnpm vitest +./run pnpm test ``` The `test` script and others are in the top-level `package.json` file. From e628f64a934ff37179ee14af45258e79e3cafa0f Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 5 Jan 2024 21:22:56 +0300 Subject: [PATCH 30/39] Empty From 7219d604a973e558d2e893a9bede096366b8e87a Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 12 Jan 2024 01:32:07 +0300 Subject: [PATCH 31/39] Updated contributing docs after review, minor fixes --- .../src/docs/community/contributing.md | 36 +++++++++++-------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index 695736cc9b..c8f49dbaad 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -48,7 +48,13 @@ 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) + +In case you do not use `volta` the following commands must be sufficient enough to start with: + +```bash +curl -fsSL https://get.pnpm.io/install.sh | sh - +pnpm env use --global 18 +``` **Docker** @@ -67,10 +73,10 @@ If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwis **Host** -Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. +Install packages: ```bash -npx pnpm install # npx is required for first install +pnpm install ``` **Docker** @@ -89,8 +95,10 @@ To get detailed help simply type `./run` or `./run help`. It also has short _Development quick start guide_ embedded. ``` +Then install packages: + ```bash -./run pnpm install # Install packages +./run pnpm install ``` ### Verify Everything Works @@ -154,7 +162,7 @@ gitGraph LR: 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. +To prepare a new version for release the maintainers 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 @@ -225,7 +233,7 @@ A bug described in issue 1123 that causes random ugly red text in multiple diagr ## Contributing Code -Code it the heart of every software project. We strive to make it better. Who if not us? +Code is the heart of every software project. We strive to make it better. Who if not us? ### Where is the Code Located? @@ -236,7 +244,7 @@ The core of Mermaid is located under `packages/mermaid/src`. **Host** ```bash -npx pnpm run dev +pnpm run dev ``` **Docker** @@ -256,7 +264,7 @@ Have a look at . There is a list of demos that can be use 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 . -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!) +After making code changes, the dev server will rebuild the mermaid library and automatically reload the page. Edit files in `packages/mermaid/src` as required. @@ -277,7 +285,7 @@ If you are adding a feature, you will definitely need to add tests. Depending on Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. -Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) +Unit tests are mandatory for all code except the renderers. (The renderers are tested with integration tests.) We use [Vitest](https://vitest.dev) to run unit tests. @@ -303,12 +311,13 @@ When using Docker prepend your command with `./run`: ./run pnpm test ``` -#### Integration/End-to-End (e2e) tests +#### Integration / End-to-End (E2E) Tests These test the rendering and visual appearance of the diagrams. -This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! -To start working with the e2e tests: +This ensures that the rendering of that feature in the E2E will be reviewed in the release process going forward. Less chance that it breaks! + +To start working with the E2E tests: **Host** @@ -345,7 +354,6 @@ it('should render forks and joins', () => { `, { logLevel: 0 } ); - cy.get('svg'); }); ``` @@ -361,7 +369,7 @@ Our documentation is managed in `packages/mermaid/src/docs`. Details on how to e 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. -The documentation has to be updated to users know that things have changed and added! +The documentation has to be updated for users to know that things have been changed and added! If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. eg: `# Feature Name (v+)` From 374e788e819d629a7348ee53e751234467409a20 Mon Sep 17 00:00:00 2001 From: nirname Date: Thu, 11 Jan 2024 22:35:39 +0000 Subject: [PATCH 32/39] Update docs --- docs/community/contributing.md | 36 +++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index ebf16cd3f0..7db91bdcd6 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -52,7 +52,13 @@ 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) + +In case you do not use `volta` the following commands must be sufficient enough to start with: + +```bash +curl -fsSL https://get.pnpm.io/install.sh | sh - +pnpm env use --global 18 +``` **Docker** @@ -71,10 +77,10 @@ If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwis **Host** -Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. +Install packages: ```bash -npx pnpm install # npx is required for first install +pnpm install ``` **Docker** @@ -92,8 +98,10 @@ chmod +x run > > It also has short _Development quick start guide_ embedded. +Then install packages: + ```bash -./run pnpm install # Install packages +./run pnpm install ``` ### Verify Everything Works @@ -156,7 +164,7 @@ gitGraph LR: 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. +To prepare a new version for release the maintainers 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 @@ -224,7 +232,7 @@ If your work is specific to a single diagram type, it is a good idea to put the ## Contributing Code -Code it the heart of every software project. We strive to make it better. Who if not us? +Code is the heart of every software project. We strive to make it better. Who if not us? ### Where is the Code Located? @@ -235,7 +243,7 @@ The core of Mermaid is located under `packages/mermaid/src`. **Host** ```bash -npx pnpm run dev +pnpm run dev ``` **Docker** @@ -255,7 +263,7 @@ Have a look at . There is a list of demos that can be use 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 . -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!) +After making code changes, the dev server will rebuild the mermaid library and automatically reload the page. Edit files in `packages/mermaid/src` as required. @@ -276,7 +284,7 @@ If you are adding a feature, you will definitely need to add tests. Depending on Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run. -Unit tests are mandatory all code except the renderers. (The renderers are tested with integration tests.) +Unit tests are mandatory for all code except the renderers. (The renderers are tested with integration tests.) We use [Vitest](https://vitest.dev) to run unit tests. @@ -302,12 +310,13 @@ When using Docker prepend your command with `./run`: ./run pnpm test ``` -#### Integration/End-to-End (e2e) tests +#### Integration / End-to-End (E2E) Tests These test the rendering and visual appearance of the diagrams. -This ensures that the rendering of that feature in the e2e will be reviewed in the release process going forward. Less chance that it breaks! -To start working with the e2e tests: +This ensures that the rendering of that feature in the E2E will be reviewed in the release process going forward. Less chance that it breaks! + +To start working with the E2E tests: **Host** @@ -344,7 +353,6 @@ it('should render forks and joins', () => { `, { logLevel: 0 } ); - cy.get('svg'); }); ``` @@ -360,7 +368,7 @@ it('should render forks and joins', () => { 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. -The documentation has to be updated to users know that things have changed and added! +The documentation has to be updated for users to know that things have been changed and added! If you are adding a new feature, add `(v+)` in the title or description. It will be replaced automatically with the current version number when the release happens. eg: `# Feature Name (v+)` From 26f6aec442810ed00ad6898920f0e5f929a58649 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 12 Jan 2024 01:57:13 +0300 Subject: [PATCH 33/39] build From a3092fc174155b5b974e8760bd120ac91060c12e Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 12 Jan 2024 02:00:30 +0300 Subject: [PATCH 34/39] Fixed dead link --- docs/intro/getting-started.md | 2 +- packages/mermaid/src/docs/.vitepress/theme/redirect.ts | 2 +- packages/mermaid/src/docs/intro/getting-started.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/intro/getting-started.md b/docs/intro/getting-started.md index c1671b098f..e304d727fc 100644 --- a/docs/intro/getting-started.md +++ b/docs/intro/getting-started.md @@ -17,7 +17,7 @@ This section talks about the different ways to **deploy** Mermaid. If you are a beginner: - Check out the [Diagram Syntax](syntax-reference.md) page -- Check out the [Tutorials](../config/Tutorials.md) page +- Check out the [Tutorials](../ecosystem/tutorials.md) page ## Ways to use Mermaid diff --git a/packages/mermaid/src/docs/.vitepress/theme/redirect.ts b/packages/mermaid/src/docs/.vitepress/theme/redirect.ts index 57cac68005..9c8151b941 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/redirect.ts +++ b/packages/mermaid/src/docs/.vitepress/theme/redirect.ts @@ -69,7 +69,7 @@ const idRedirectMap: Record = { statediagram: 'syntax/stateDiagram', themes: 'config/theming', theming: 'config/theming', - tutorials: 'config/Tutorials', + tutorials: 'ecosystem/tutorials', upgrading: '', usage: 'config/usage', 'user-journey': 'syntax/userJourney', diff --git a/packages/mermaid/src/docs/intro/getting-started.md b/packages/mermaid/src/docs/intro/getting-started.md index 81b180763f..1a97fcfbfd 100644 --- a/packages/mermaid/src/docs/intro/getting-started.md +++ b/packages/mermaid/src/docs/intro/getting-started.md @@ -15,7 +15,7 @@ This section talks about the different ways to **deploy** Mermaid. If you are a beginner: - Check out the [Diagram Syntax](syntax-reference.md) page -- Check out the [Tutorials](../config/Tutorials.md) page +- Check out the [Tutorials](../ecosystem/tutorials.md) page ## Ways to use Mermaid From f6b321d7697b95981b14c5b2aa3c80386eaf1781 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Sat, 13 Jan 2024 15:19:36 +0300 Subject: [PATCH 35/39] Removed volta requirement, leave pnpm only --- Dockerfile | 2 + docker-compose.yml | 5 ++- docker-entrypoint.sh | 3 ++ .../src/docs/community/contributing.md | 9 ++-- run | 42 +++++++++++-------- 5 files changed, 38 insertions(+), 23 deletions(-) create mode 100644 Dockerfile create mode 100755 docker-entrypoint.sh diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..a62800109c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,2 @@ +FROM node:18.19.0-alpine3.18 AS base +RUN wget -qO- https://get.pnpm.io/install.sh | ENV="$HOME/.shrc" SHELL="$(which sh)" sh - diff --git a/docker-compose.yml b/docker-compose.yml index 733f5d9a72..1c6f4458ae 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,11 +1,14 @@ version: '3.9' services: mermaid: - image: node:18.19.0-alpine3.18 + build: + context: . + dockerfile: Dockerfile stdin_open: true tty: true working_dir: /mermaid mem_limit: '8G' + entrypoint: "/mermaid/docker-entrypoint.sh" environment: - NODE_OPTIONS=--max_old_space_size=8192 volumes: diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh new file mode 100755 index 0000000000..c222b7fd50 --- /dev/null +++ b/docker-entrypoint.sh @@ -0,0 +1,3 @@ +#!/bin/sh +source /root/.shrc +exec "$@" diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index c8f49dbaad..9a83b5294c 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -45,17 +45,18 @@ We support **development within Docker** environment along with **host setup**. 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` +- [Node.js](https://nodejs.org/en/). +- [pnpm](https://pnpm.io/) package manager. -In case you do not use `volta` the following commands must be sufficient enough to start with: +The following commands must be sufficient enough to start with: ```bash curl -fsSL https://get.pnpm.io/install.sh | sh - pnpm env use --global 18 ``` +You may also need to reload `.shrc` or `.bashrc` afterwards. + **Docker** [Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. diff --git a/run b/run index 920e346f83..ea23d28de6 100755 --- a/run +++ b/run @@ -1,5 +1,5 @@ #!/bin/bash -RUN="docker-compose run --rm" +RUN="docker compose run --rm" ansi() { echo -e "\e[${1}m${*:2}\e[0m"; } bold() { ansi 1 "$@"; } @@ -14,16 +14,20 @@ args=${@:2} case $command in +build) +docker compose build $args +;; + sh) -$RUN mermaid sh -c "npx $args" +$RUN mermaid sh # -c "npx $args" ;; pnpm) -$RUN mermaid sh -c "npx pnpm $args" +$RUN mermaid sh -c "pnpm $args" ;; dev) -$RUN --service-ports mermaid sh -c "npx pnpm run dev" +$RUN --service-ports mermaid sh -c "pnpm run dev" ;; docs:dev) @@ -46,24 +50,26 @@ Welcome! Thank you for joining the development. This is a script for running commands within docker containers at ease. __________________________________________________________________________________________ -Development quick start guide: +Development Quick Start Guide: + +$(bold ./$name pnpm install) # Install packages +$(bold ./$name dev) # Launch dev server with examples, open http://localhost:9000 +$(bold ./$name docs:dev) # Launch official website, open http://localhost:3333 -$(bold ./$name pnpm install) # Install packages -$(bold ./$name dev) # Run dev server with examples, open http://localhost:9000 -$(bold ./$name pnpm vitest) # Run watcher for unit tests -$(bold ./$name cypress) # Run integration tests (after starting dev server) -$(bold ./$name pnpm build) # Prepare it for production -$(bold ./$name docs:dev) # Then add documentation, open http://localhost:3333 +$(bold ./$name pnpm vitest) # Run watcher for unit tests +$(bold ./$name cypress) # Run integration tests (after starting dev server) +$(bold ./$name pnpm build) # Prepare it for production __________________________________________________________________________________________ Commands: -$(bold ./$name pnpm) # Run any 'pnpm' command -$(bold ./$name dev) # Run dev server with examples, open http://localhost:9000 -$(bold ./$name docs:dev) # For docs contributions, open http://localhost:3333 -$(bold ./$name cypress) # Run integration tests -$(bold ./$name sh) # Open 'sh' inside docker container for development -$(bold ./$name help) # Show this help +$(bold ./$name build) # Build image +$(bold ./$name cypress) # Run integration tests +$(bold ./$name dev) # Run dev server with examples, open http://localhost:9000 +$(bold ./$name docs:dev) # For docs contributions, open http://localhost:3333 +$(bold ./$name help) # Show this help +$(bold ./$name pnpm) # Run any 'pnpm' command +$(bold ./$name sh) # Open 'sh' inside docker container for development __________________________________________________________________________________________ Examples of frequiently used commands: @@ -81,7 +87,7 @@ $(bold ./$name cypress open --project .) Open cypress interactive GUI $(bold ./$name cypress run --spec cypress/integration/rendering/)$(underline test.spec.ts) - Run specific test in cypress\n + Run specific test in cypress $(bold xhost +local:) Allow local connections for x11 server From 621d6cbda124f87946e050c4b915d46a62bc0f23 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Sat, 13 Jan 2024 23:38:11 +0300 Subject: [PATCH 36/39] Fix linters --- docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose.yml b/docker-compose.yml index 1c6f4458ae..90546a4d64 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -8,7 +8,7 @@ services: tty: true working_dir: /mermaid mem_limit: '8G' - entrypoint: "/mermaid/docker-entrypoint.sh" + entrypoint: '/mermaid/docker-entrypoint.sh' environment: - NODE_OPTIONS=--max_old_space_size=8192 volumes: From 3290c382605eac5441d022e89834237d445df5ec Mon Sep 17 00:00:00 2001 From: nirname Date: Sat, 13 Jan 2024 20:41:27 +0000 Subject: [PATCH 37/39] Update docs --- docs/community/contributing.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 7db91bdcd6..d6afbd90d9 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -49,17 +49,18 @@ We support **development within Docker** environment along with **host setup**. 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` +- [Node.js](https://nodejs.org/en/). +- [pnpm](https://pnpm.io/) package manager. -In case you do not use `volta` the following commands must be sufficient enough to start with: +The following commands must be sufficient enough to start with: ```bash curl -fsSL https://get.pnpm.io/install.sh | sh - pnpm env use --global 18 ``` +You may also need to reload `.shrc` or `.bashrc` afterwards. + **Docker** [Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. From 385bf328c255c181985773ad7b7ccac77d8e1462 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Sun, 14 Jan 2024 01:05:47 +0300 Subject: [PATCH 38/39] Remove npx completely from run script --- run | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/run b/run index ea23d28de6..d7aee23296 100755 --- a/run +++ b/run @@ -19,7 +19,7 @@ docker compose build $args ;; sh) -$RUN mermaid sh # -c "npx $args" +$RUN mermaid sh ;; pnpm) From bafb991a355f4a8d46c9475a0963ca2b7966cec9 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Sun, 14 Jan 2024 01:07:37 +0300 Subject: [PATCH 39/39] Run dev docs without npx --- run | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/run b/run index d7aee23296..3ea990e122 100755 --- a/run +++ b/run @@ -31,7 +31,7 @@ $RUN --service-ports mermaid sh -c "pnpm run dev" ;; docs:dev) -$RUN --service-ports mermaid sh -c "npx pnpm run --filter mermaid docs:dev:docker" +$RUN --service-ports mermaid sh -c "pnpm run --filter mermaid docs:dev:docker" ;; cypress)