From 57f0a3aa8e0afe79b582dc13c10129ee181cb091 Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Mon, 11 Dec 2023 05:08:42 +0300 Subject: [PATCH 01/50] 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 6a1cc85e5..e6728b03f 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 e2484bdc5..a48cf5b8a 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 3689cb68b..42e299c54 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 8601664fa..db1fdfef0 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 93a5fcd95..b1f225d50 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 89e08b3f7..753c1d4b9 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 6a0df983d..2c33af410 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 000000000..953f98e67 --- /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 000000000..84ae492ea --- /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 fc11a1f6c..2545d315a 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 000000000..313fd1078 --- /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 4ab477428..000000000 --- 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 000000000..013cf3ce0 --- /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 1a872627c..0df111ebd 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/50] 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 953f98e67..633282b14 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/50] 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 753c1d4b9..6e6d421ca 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 633282b14..3d618d153 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 2545d315a..ac087ad9e 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 313fd1078..ad1978953 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/50] 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 db1fdfef0..a1e7b05f8 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 2c33af410..cb5d03898 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 3d618d153..91a58393f 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 84ae492ea..000000000 --- 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 ac087ad9e..7574081f3 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 1e85102ce..f18591376 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 421240729..b848a90aa 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 7d0e90024..f7f306b94 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 23306acdd..1f4bcbc4b 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/50] Contribution guidelines rework --- CONTRIBUTING.md | 79 +------------ packages/mermaid/src/docs/community/code.md | 97 +++++----------- .../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 | 102 ++++++++++------- .../mermaid/src/docs/community/workflow.md | 4 +- 8 files changed, 206 insertions(+), 328 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 3142c5760..000000000 --- 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 000000000..885868c16 --- /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 b1f225d50..129638da5 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] +The core of Mermaid is located under `packages/mermaid/src`. + +## Running Mermaid Locally + +**Host** + +```bash +npx pnpm run dev ``` -1. **Create** and checkout a git branch and work on your code in the branch -2. Write and update **tests** (unit and perhaps even integration (e2e) tests) (If you do TDD/BDD, the order might be different.) -3. **Let users know** that things have changed or been added in the documents! This is often overlooked, but _critical_ -4. **Submit** your code as a _pull request_. -5. Maintainers will **review** your code. If there are no changes necessary, the PR will be merged. Otherwise, make the requested changes and repeat. +**Docker** -## 1. Checkout a git branch - -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. - -Development is done in the `develop` branch. - -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. - -Once the release happens we add a tag to the `release` branch and merge it with `master`. The live product and on-line documentation are what is in the `master` branch. - -**All new work should be based on the `develop` branch.** - -**When you are ready to do work, always, ALWAYS:** - -1. Make sure you have the most up-to-date version of the `develop` branch. (fetch or pull to update it) -2. Check out the `develop` branch -3. Create a new branch for your work. Please name the branch following our naming convention below. - -We use the following naming convention for branches: - -```txt - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] +```bash +./run dev ``` -You can always check current [configuration of labelling and branch prefixes](https://github.com/mermaid-js/mermaid/blob/develop/.github/pr-labeler.yml) +After starting the dev server open 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 000000000..f055e1319 --- /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 6e6d421ca..000000000 --- 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 cb5d03898..3b5797635 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 91a58393f..3783e678b 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 7574081f3..8db29242c 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,12 +6,39 @@ Initial setup consists of 3 main steps: flowchart LR source --> requirements --> setup - source[Get the source code] requirements[Install the requirements] - setup[Setup and launch] - + source[Get the source code] + setup[Install packages] ``` +## Choose Your Environment + +We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. + +## Install Requirements + +### Host + +These are the tools we use for working with the code and documentation: + +- [volta](https://volta.sh/) to manage node versions. +- [Node.js](https://nodejs.org/en/). `volta install node` +- [pnpm](https://pnpm.io/) package manager. `volta install pnpm` +- [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) + +### Docker + +[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. + +Optionally, to run GUI (Cypress) within Docker you will also need an X11 server installed. +You might already have it installed, so check this by running: + +```bash +echo $DISPLAY +``` + +If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one. + ## Get the Source Code In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. @@ -26,24 +49,9 @@ Then you **clone** a copy to your local development machine (e.g. where you code [Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo). -## Technical Requirements - -> The following documentation describes how to work with Mermaid in your host environment. -> There's also a [Docker installation guide](../community/docker-setup.md) -> if you prefer to work in a Docker environment. - -These are the tools we use for working with the code and documentation: - -- [volta](https://volta.sh/) to manage node versions. -- [Node.js](https://nodejs.org/en/). `volta install node` -- [pnpm](https://pnpm.io/) package manager. `volta install pnpm` -- [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) - -Follow the setup steps below to start the development. - -## Setup and Launch - -### Switch to project +```bash +git clone git@github.com/your-fork/mermaid +``` Once you have cloned the repository onto your development machine, change into the `mermaid` project folder (the top level directory of the mermaid project repository) @@ -51,44 +59,54 @@ Once you have cloned the repository onto your development machine, change into t cd mermaid ``` -### Install packages +## Setup -Run `npx pnpm install`. You will need `npx` for this because volta doesn't support it yet. +### Host + +Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. ```bash npx pnpm install # npx is required for first install ``` -### Launch Mermaid +### Docker + +For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. + +Make sure that `./run` script is executable: ```bash -npx pnpm run dev +chmod +x run ``` -Now you are ready to make your changes! Edit whichever files in `src` as required. +```tip +To get detailed help simply type `./run` or `./run help`. -Open in your browser, after starting the dev server. -There is a list of demos that can be used to see and test your changes. +It also has short _Development quick start guide_ embedded. +``` -If you need a specific diagram, you can duplicate the `example.html` file in `/demos/dev` and add your own mermaid code to your copy. +```bash +./run pnpm install # Install packages +``` -That will be served at . -After making code changes, the dev server will rebuild the mermaid library. You will need to reload the browser page yourself to see the changes. (PRs for auto reload are welcome!) - -### Launch Documentaion Website - - - -## Verify Everything is Working +## Verify Everything Works This step is optional, but it helps to make sure that everything in development branch was OK before you started making any changes. You can run the `test` script to verify that pnpm is working _and_ that the repository has been cloned correctly: +**Host** + ```bash pnpm test ``` +**Docker** + +```bash +./run pnpm test +``` + The `test` script and others are in the top-level `package.json` file. All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) diff --git a/packages/mermaid/src/docs/community/workflow.md b/packages/mermaid/src/docs/community/workflow.md index ad1978953..c0cf1c3e6 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/50] 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 ff34d24fd..4934163b5 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 c9d8dab97..000000000 --- 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 9df0c8d59..000000000 --- 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 28c0ca724..000000000 --- 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 a1e7b05f8..ca5e49a1b 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 f055e1319..8bce7c2e9 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 3b5797635..bd5acad12 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 3783e678b..7ff1ced1e 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/50] Update docs --- docs/community/code.md | 94 +++----- docs/community/contributing.md | 78 +++++++ docs/community/documentation.md | 79 +++---- 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, 1341 insertions(+), 111 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 e77a25467..473a6da0e 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] +## Where is the code located? + +The core of Mermaid is located under `packages/mermaid/src`. + +## Running Mermaid Locally + +**Host** + +```bash +npx pnpm run dev ``` -```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] +**Docker** + +```bash +./run dev ``` -1. **Create** and checkout a git branch and work on your code in the branch -2. Write and update **tests** (unit and perhaps even integration (e2e) tests) (If you do TDD/BDD, the order might be different.) -3. **Let users know** that things have changed or been added in the documents! This is often overlooked, but _critical_ -4. **Submit** your code as a _pull request_. -5. Maintainers will **review** your code. If there are no changes necessary, the PR will be merged. Otherwise, make the requested changes and repeat. +After starting the dev server open in your browser. -## 1. Checkout a git branch +Now you are ready to make your changes! -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. +## Make Changes -Development is done in the `develop` branch. +Have a look at . There is a list of demos that can be used to see and test your changes. -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. +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. -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. +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!) -**All new work should be based on the `develop` branch.** +Edit files in `packages/mermaid/src` as required. -**When you are ready to do work, always, ALWAYS:** - -1. Make sure you have the most up-to-date version of the `develop` branch. (fetch or pull to update it) -2. Check out the `develop` branch -3. Create a new branch for your work. Please name the branch following our naming convention below. - -We use the following naming convention for branches: - -```txt - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] -``` - -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, 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) - -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. - -**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` - -**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 +## 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 000000000..c50f4ea05 --- /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 67d35d395..28c7ede89 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. +## Where is the Documentation Located? -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. +> **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. -## How to Contribute to Documentation +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. -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. - -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 000000000..73392e62c --- /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 b90d192b2..e3febb8f5 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 000000000..6fd401892 --- /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 000000000..0f142108b --- /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 000000000..435c8e608 --- /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 000000000..4d4876510 --- /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 000000000..8feda2799 --- /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 000000000..3f9f5f98e --- /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 000000000..5162886b8 --- /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 000000000..a8ab8e707 --- /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 000000000..d43613c95 --- /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 000000000..881514371 --- /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 f3bad9ade..36d5ad93f 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/50] 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 000000000..843e9e622 --- /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 ca5e49a1b..b151e6175 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 129638da5..1c4f0946c 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 8bce7c2e9..67b814d20 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) -## Development Installation +#### Docker -If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js: +[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 -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 -### Docker +For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. -If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands: +Make sure that `./run` script is executable: ```bash -./run install # npx pnpm install -./run test # pnpm test +chmod +x run ``` -## Testing +```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 -# Run unit test pnpm test -# Run unit test in watch mode +``` + +**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 + +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 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 +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 -# 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 -```text - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] +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'); +}); ``` -eg: `feature/2945_state-diagram-new-arrow-florbs`, `bug/1123_fix_random_ugly_red_text` + + -## Documentation +### Update Documentation -Documentation is necessary for all non bugfix/refactoring changes. +```tip +Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](documentation) +``` -Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +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. -**_DO NOT CHANGE FILES IN `/docs` MANUALLY_** +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. -The `/docs` folder will be rebuilt and committed as part of a pre-commit hook. +eg: `# Feature Name (v+)` -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +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 +``` + +```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 # +``` + +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/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index bd5acad12..b817fd224 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 8db29242c..6a637cc4f 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 -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. +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: @@ -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 c0cf1c3e6..c707e5138 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/50] 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 473a6da0e..44cf4e062 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 c50f4ea05..5320681dc 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) -## Development Installation +#### Docker -If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js: +[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 -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 -### Docker +For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. -If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands: +Make sure that `./run` script is executable: ```bash -./run install # npx pnpm install -./run test # pnpm test +chmod +x run ``` -## Testing +> **💡 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 -# Run unit test pnpm test -# Run unit test in watch mode +``` + +**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 + +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). + +## 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 -# 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 -```text - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] +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'); +}); ``` -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. +### Update Documentation -Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +> **💡 Tip** +> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](documentation) -**_DO NOT CHANGE FILES IN `/docs` MANUALLY_** +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 `/docs` folder will be rebuilt and committed as part of a pre-commit hook. +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. -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +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 + + 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 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 +``` +```` + +### 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 # +``` + +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/community/documentation.md b/docs/community/documentation.md index 28c7ede89..2b2cc0105 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 6fd401892..33c13519d 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 -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. +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: @@ -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 0f142108b..19d5ca165 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 435c8e608..a3dbfcb2a 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 4d4876510..ed0791ee8 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) -## Development Installation +#### Docker -If you don't have direct access to push to mermaid repositories, make a fork first. Then clone. Or clone directly from mermaid-js: +[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 -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 -### Docker +For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. -If you are using docker and docker-compose, you have self-documented `run` bash script, which is a convenient alias for docker-compose commands: +Make sure that `./run` script is executable: ```bash -./run install # npx pnpm install -./run test # pnpm test +chmod +x run ``` -## Testing +> **💡 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 -# Run unit test pnpm test -# Run unit test in watch mode +``` + +**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 + +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). + +## 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 -# 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 -```text - [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces] +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'); +}); ``` -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. +### Update Documentation -Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +> **💡 Tip** +> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](documentation) -**_DO NOT CHANGE FILES IN `/docs` MANUALLY_** +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 `/docs` folder will be rebuilt and committed as part of a pre-commit hook. +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. -[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) +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 + + 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 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 +``` +```` + +### 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 # +``` + +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/documentation.md b/docs/contributing/documentation.md index 8feda2799..17e787609 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 d43613c95..952eb8b69 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 -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. +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: @@ -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 881514371..bb389bdb9 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/50] 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 1c4f0946c..2b4d24962 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 67b814d20..eb2c03ce1 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 b817fd224..30702ea36 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 c707e5138..5783125f9 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/50] 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 44cf4e062..c7f364735 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 5320681dc..8218f31ca 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 2b2cc0105..a321c882c 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 19d5ca165..2ccc36e05 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 a3dbfcb2a..73fc89f27 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 ed0791ee8..af5388af3 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 17e787609..59fb3a941 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 bb389bdb9..f31cc8afa 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/50] 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 b151e6175..4cd9e2843 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 eb2c03ce1..57f604080 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,30 +113,49 @@ 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 +Contributing process is very simple and strightforward: + +```mermaid-nocode + 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. -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 - - 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 @@ -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 ``` ```` +```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). +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 30702ea36..ce1136973 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/50] Update docs --- docs/community/contributing.md | 90 ++++++++++++++++++++---------- docs/community/documentation.md | 4 +- docs/contributing/contributing.md | 90 ++++++++++++++++++++---------- docs/contributing/documentation.md | 4 +- 4 files changed, 126 insertions(+), 62 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 8218f31ca..9f2af0092 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 +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. -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 - - 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 ``` ```` +> **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). +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 a321c882c..cd9fb277c 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 af5388af3..595fccf0a 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 +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. -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 - - 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 ``` ```` +> **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). +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 59fb3a941..550adc6d3 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/50] 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 6f8d4c6b7..733f5d9a7 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 4cd9e2843..c7d29b277 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 2b4d24962..000000000 --- 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 57f604080..71a4f4b2d 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 ce1136973..000000000 --- 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 7ff1ced1e..e700fde45 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: -## Where do I 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). -- 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) +[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/packages/mermaid/src/docs/community/questions-and-suggestions.md b/packages/mermaid/src/docs/community/questions-and-suggestions.md index 386e3753a..6408d7fed 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/50] 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 c7f364735..000000000 --- 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 9f2af0092..5eb17ead9 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 cd9fb277c..000000000 --- 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 73392e62c..9f515f8c0 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 badb53a35..8dbfae008 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 73fc89f27..000000000 --- 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 595fccf0a..16832391c 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 550adc6d3..000000000 --- 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 c7759b60d..9297c7d5f 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 5162886b8..ebe85b417 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/50] 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 5eb17ead9..0110e7145 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 71a4f4b2d..5dcf012b8 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/50] 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 16832391c..90048ba03 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/50] 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 cf21fdb8e..5acafa95d 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 98975ea33..23c9bc722 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 7603906c1..6318fbe81 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 535ee3a3d..c159ec687 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/50] 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 95d7b594e..061e625d7 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 5a77fa587..3c5cae757 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/50] 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/50] 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 90048ba03..f63f71f5f 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 6a637cc4f..000000000 --- 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 5783125f9..000000000 --- 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 ae3ad0f0a..67ed9c067 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/50] 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 33c13519d..000000000 --- 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 2ccc36e05..000000000 --- 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 8bd34345f..7c3bc2675 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 f63f71f5f..90048ba03 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 952eb8b69..000000000 --- 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 f31cc8afa..000000000 --- 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/50] 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 5dcf012b8..5a54b8757 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 67ed9c067..5019611a7 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 6318fbe81..3d29e4231 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 c159ec687..2a7ef13ba 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/50] 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 0110e7145..d61ab25c4 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 7c3bc2675..6ef621f98 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 90048ba03..a61f5311b 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 061e625d7..c1be9ccec 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 3c5cae757..79ef53b4b 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/50] 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 4934163b5..f20204a71 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 843e9e622..000000000 --- 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 c7d29b277..710aa6b2d 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 013cf3ce0..000000000 --- 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 fbf437263..aeaccb474 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/50] 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 a61f5311b..000000000 --- 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 3f9f5f98e..000000000 --- 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 ebe85b417..000000000 --- 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 a8ab8e707..000000000 --- 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/50] 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 d61ab25c4..614e0599f 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 710aa6b2d..5a2509820 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 09c14d935..9455882c5 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 e24d2beb9..57cac6800 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 5a54b8757..695736cc9 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/50] 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 9455882c5..7a5481a59 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 aeaccb474..920e346f8 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/50] 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 614e0599f..ebf16cd3f 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 e52fcd0bdda31046285d48261d14a32d39dd637a Mon Sep 17 00:00:00 2001 From: murdoa Date: Thu, 11 Jan 2024 22:24:50 +0000 Subject: [PATCH 31/50] Updated gantt chart docs to show all config options --- docs/syntax/gantt.md | 20 +++++++++++++++----- packages/mermaid/src/docs/syntax/gantt.md | 20 +++++++++++++++----- 2 files changed, 30 insertions(+), 10 deletions(-) diff --git a/docs/syntax/gantt.md b/docs/syntax/gantt.md index 33c2740e5..07fc897ec 100644 --- a/docs/syntax/gantt.md +++ b/docs/syntax/gantt.md @@ -420,11 +420,21 @@ mermaid.ganttConfig can be set to a JSON string with config parameters or the co ```javascript mermaid.ganttConfig = { - titleTopMargin: 25, - barHeight: 20, - barGap: 4, - topPadding: 75, - sidePadding: 75, + titleTopMargin: 25, // Margin top for the text over the diagram + barHeight: 20, // The height of the bars in the graph + barGap: 4, // The margin between the different activities in the gantt diagram + topPadding: 75, // Margin between title and gantt diagram and between axis and gantt diagram. + rightPadding: 75, // The space allocated for the section name to the right of the activities + leftPadding: 75, // The space allocated for the section name to the left of the activities + gridLineStartPadding: 10, // Vertical starting position of the grid lines + fontSize: 12, // Font size + sectionFontSize: 24, // Font size for sections + numberSectionStyles: 1, // The number of alternating section styles + axisFormat: '%d/%m', // Date/time format of the axis + tickInterval: '1 week', // Axis ticks + topAxis: true, // When this flag is set, date labels will be added to the top of the chart + displayMode: 'compact', // Turns compact mode on + weekday: 'sunday', // On which day a week-based interval should start }; ``` diff --git a/packages/mermaid/src/docs/syntax/gantt.md b/packages/mermaid/src/docs/syntax/gantt.md index a0cebc560..6940f882f 100644 --- a/packages/mermaid/src/docs/syntax/gantt.md +++ b/packages/mermaid/src/docs/syntax/gantt.md @@ -325,11 +325,21 @@ mermaid.ganttConfig can be set to a JSON string with config parameters or the co ```javascript mermaid.ganttConfig = { - titleTopMargin: 25, - barHeight: 20, - barGap: 4, - topPadding: 75, - sidePadding: 75, + titleTopMargin: 25, // Margin top for the text over the diagram + barHeight: 20, // The height of the bars in the graph + barGap: 4, // The margin between the different activities in the gantt diagram + topPadding: 75, // Margin between title and gantt diagram and between axis and gantt diagram. + rightPadding: 75, // The space allocated for the section name to the right of the activities + leftPadding: 75, // The space allocated for the section name to the left of the activities + gridLineStartPadding: 10, // Vertical starting position of the grid lines + fontSize: 12, // Font size + sectionFontSize: 24, // Font size for sections + numberSectionStyles: 1, // The number of alternating section styles + axisFormat: '%d/%m', // Date/time format of the axis + tickInterval: '1 week', // Axis ticks + topAxis: true, // When this flag is set, date labels will be added to the top of the chart + displayMode: 'compact', // Turns compact mode on + weekday: 'sunday', // On which day a week-based interval should start }; ``` From 7219d604a973e558d2e893a9bede096366b8e87a Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 12 Jan 2024 01:32:07 +0300 Subject: [PATCH 32/50] 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 695736cc9..c8f49dbaa 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 33/50] 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 ebf16cd3f..7db91bdcd 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 a3092fc174155b5b974e8760bd120ac91060c12e Mon Sep 17 00:00:00 2001 From: Nikolay Rozhkov Date: Fri, 12 Jan 2024 02:00:30 +0300 Subject: [PATCH 35/50] 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 c1671b098..e304d727f 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 57cac6800..9c8151b94 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 81b180763..1a97fcfbf 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 36/50] 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 000000000..a62800109 --- /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 733f5d9a7..1c6f4458a 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 000000000..c222b7fd5 --- /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 c8f49dbaa..9a83b5294 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 920e346f8..ea23d28de 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) # 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 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 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 37/50] Fix linters --- docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose.yml b/docker-compose.yml index 1c6f4458a..90546a4d6 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 38/50] 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 7db91bdcd..d6afbd90d 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 39/50] Remove npx completely from run script --- run | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/run b/run index ea23d28de..d7aee2329 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 40/50] Run dev docs without npx --- run | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/run b/run index d7aee2329..3ea990e12 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) From 0e7e597384ff4218238c6f24db1d04cf25ff2393 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 15 Jan 2024 09:18:38 +0000 Subject: [PATCH 41/50] build(deps-dev): bump follow-redirects from 1.15.2 to 1.15.5 Bumps [follow-redirects](https://github.com/follow-redirects/follow-redirects) from 1.15.2 to 1.15.5. - [Release notes](https://github.com/follow-redirects/follow-redirects/releases) - [Commits](https://github.com/follow-redirects/follow-redirects/compare/v1.15.2...v1.15.5) --- updated-dependencies: - dependency-name: follow-redirects dependency-type: indirect ... Signed-off-by: dependabot[bot] --- pnpm-lock.yaml | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f6f1897f6..3a6dd48d7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -6851,7 +6851,7 @@ packages: /axios@0.27.2(debug@4.3.4): resolution: {integrity: sha512-t+yRIyySRTp/wua5xEr+z1q60QmLq8ABsS5O9Me1AsE5dfKqgnCFzwiCZZ/cGNd1lq4/7akDWMxdhVlucjmnOQ==} dependencies: - follow-redirects: 1.15.2(debug@4.3.4) + follow-redirects: 1.15.5(debug@4.3.4) form-data: 4.0.0 transitivePeerDependencies: - debug @@ -10094,9 +10094,19 @@ packages: tabbable: 6.2.0 dev: true - /follow-redirects@1.15.2(debug@4.3.4): + /follow-redirects@1.15.2: resolution: {integrity: sha512-VQLG33o04KaQ8uYi2tVNbdrWp1QWxNNea+nmIB4EVM28v0hmP17z7aG1+wAkNzVq4KeXTq3221ye5qTJP91JwA==} engines: {node: '>=4.0'} + peerDependencies: + debug: '*' + peerDependenciesMeta: + debug: + optional: true + dev: true + + /follow-redirects@1.15.5(debug@4.3.4): + resolution: {integrity: sha512-vSFWUON1B+yAw1VN4xMfxgn5fTUiaOzAJCKBwIIgT/+7CuGy9+r+5gITvP62j3RmaD5Ph65UaERdOSRGUzZtgw==} + engines: {node: '>=4.0'} peerDependencies: debug: '*' peerDependenciesMeta: @@ -10846,7 +10856,7 @@ packages: engines: {node: '>=8.0.0'} dependencies: eventemitter3: 4.0.7 - follow-redirects: 1.15.2(debug@4.3.4) + follow-redirects: 1.15.2 requires-port: 1.0.0 transitivePeerDependencies: - debug From 8c7edebe9352ce41483a37da6eeff77c3507f86a Mon Sep 17 00:00:00 2001 From: Matheus Braga Date: Tue, 16 Jan 2024 13:21:31 -0300 Subject: [PATCH 42/50] Revert "Revert 5041 feature/4935 subgraph title margin config option" --- .../rendering/flowchart-v2.spec.js | 89 +++++++++++++++++++ packages/mermaid/src/config.type.ts | 8 ++ .../mermaid/src/dagre-wrapper/clusters.js | 19 ++-- packages/mermaid/src/dagre-wrapper/edges.js | 13 +-- packages/mermaid/src/dagre-wrapper/index.js | 22 ++++- .../mermaid/src/schemas/config.schema.yaml | 15 ++++ .../src/utils/subGraphTitleMargins.spec.ts | 22 +++++ .../mermaid/src/utils/subGraphTitleMargins.ts | 21 +++++ 8 files changed, 194 insertions(+), 15 deletions(-) create mode 100644 packages/mermaid/src/utils/subGraphTitleMargins.spec.ts create mode 100644 packages/mermaid/src/utils/subGraphTitleMargins.ts diff --git a/cypress/integration/rendering/flowchart-v2.spec.js b/cypress/integration/rendering/flowchart-v2.spec.js index b7583ccf1..e23820ffa 100644 --- a/cypress/integration/rendering/flowchart-v2.spec.js +++ b/cypress/integration/rendering/flowchart-v2.spec.js @@ -886,4 +886,93 @@ end }); }); }); + describe('Subgraph title margins', () => { + it('Should render subgraphs with title margins set (LR)', () => { + imgSnapshotTest( + `flowchart LR + + subgraph TOP + direction TB + subgraph B1 + direction RL + i1 -->f1 + end + subgraph B2 + direction BT + i2 -->f2 + end + end + A --> TOP --> B + B1 --> B2 + `, + { flowchart: { subGraphTitleMargin: { top: 10, bottom: 5 } } } + ); + }); + it('Should render subgraphs with title margins set (TD)', () => { + imgSnapshotTest( + `flowchart TD + + subgraph TOP + direction LR + subgraph B1 + direction RL + i1 -->f1 + end + subgraph B2 + direction BT + i2 -->f2 + end + end + A --> TOP --> B + B1 --> B2 + `, + { flowchart: { subGraphTitleMargin: { top: 8, bottom: 16 } } } + ); + }); + it('Should render subgraphs with title margins set (LR) and htmlLabels set to false', () => { + imgSnapshotTest( + `flowchart LR + + subgraph TOP + direction TB + subgraph B1 + direction RL + i1 -->f1 + end + subgraph B2 + direction BT + i2 -->f2 + end + end + A --> TOP --> B + B1 --> B2 + `, + { + htmlLabels: false, + flowchart: { htmlLabels: false, subGraphTitleMargin: { top: 10, bottom: 5 } }, + } + ); + }); + it('Should render subgraphs with title margins and edge labels', () => { + imgSnapshotTest( + `flowchart LR + + subgraph TOP + direction TB + subgraph B1 + direction RL + i1 --lb1-->f1 + end + subgraph B2 + direction BT + i2 --lb2-->f2 + end + end + A --lb3--> TOP --lb4--> B + B1 --lb5--> B2 + `, + { flowchart: { subGraphTitleMargin: { top: 10, bottom: 5 } } } + ); + }); + }); }); diff --git a/packages/mermaid/src/config.type.ts b/packages/mermaid/src/config.type.ts index 2965dc0da..a5bc22f6f 100644 --- a/packages/mermaid/src/config.type.ts +++ b/packages/mermaid/src/config.type.ts @@ -1416,6 +1416,14 @@ export interface FlowchartDiagramConfig extends BaseDiagramConfig { * Margin top for the text over the diagram */ titleTopMargin?: number; + /** + * Defines a top/bottom margin for subgraph titles + * + */ + subGraphTitleMargin?: { + top?: number; + bottom?: number; + }; arrowMarkerAbsolute?: boolean; /** * The amount of padding around the diagram as a whole so that embedded diff --git a/packages/mermaid/src/dagre-wrapper/clusters.js b/packages/mermaid/src/dagre-wrapper/clusters.js index 5c6e5a4e0..2de3f2489 100644 --- a/packages/mermaid/src/dagre-wrapper/clusters.js +++ b/packages/mermaid/src/dagre-wrapper/clusters.js @@ -5,9 +5,11 @@ import { createText } from '../rendering-util/createText.js'; import { select } from 'd3'; import { getConfig } from '../diagram-api/diagramAPI.js'; import { evaluate } from '../diagrams/common/common.js'; +import { getSubGraphTitleMargins } from '../utils/subGraphTitleMargins.js'; const rect = (parent, node) => { log.info('Creating subgraph rect for ', node.id, node); + const siteConfig = getConfig(); // Add outer g element const shapeSvg = parent @@ -18,7 +20,7 @@ const rect = (parent, node) => { // add the rect const rect = shapeSvg.insert('rect', ':first-child'); - const useHtmlLabels = evaluate(getConfig().flowchart.htmlLabels); + const useHtmlLabels = evaluate(siteConfig.flowchart.htmlLabels); // Create the label and insert it after the rect const label = shapeSvg.insert('g').attr('class', 'cluster-label'); @@ -34,7 +36,7 @@ const rect = (parent, node) => { // Get the size of the label let bbox = text.getBBox(); - if (evaluate(getConfig().flowchart.htmlLabels)) { + if (evaluate(siteConfig.flowchart.htmlLabels)) { const div = text.children[0]; const dv = select(text); bbox = div.getBoundingClientRect(); @@ -63,17 +65,18 @@ const rect = (parent, node) => { .attr('width', width) .attr('height', node.height + padding); + const { subGraphTitleTopMargin } = getSubGraphTitleMargins(siteConfig); if (useHtmlLabels) { label.attr( 'transform', // This puts the labal on top of the box instead of inside it - 'translate(' + (node.x - bbox.width / 2) + ', ' + (node.y - node.height / 2) + ')' + `translate(${node.x - bbox.width / 2}, ${node.y - node.height / 2 + subGraphTitleTopMargin})` ); } else { label.attr( 'transform', // This puts the labal on top of the box instead of inside it - 'translate(' + node.x + ', ' + (node.y - node.height / 2) + ')' + `translate(${node.x}, ${node.y - node.height / 2 + subGraphTitleTopMargin})` ); } // Center the label @@ -127,6 +130,8 @@ const noteGroup = (parent, node) => { return shapeSvg; }; const roundedWithTitle = (parent, node) => { + const siteConfig = getConfig(); + // Add outer g element const shapeSvg = parent.insert('g').attr('class', node.classes).attr('id', node.id); @@ -143,7 +148,7 @@ const roundedWithTitle = (parent, node) => { // Get the size of the label let bbox = text.getBBox(); - if (evaluate(getConfig().flowchart.htmlLabels)) { + if (evaluate(siteConfig.flowchart.htmlLabels)) { const div = text.children[0]; const dv = select(text); bbox = div.getBoundingClientRect(); @@ -175,6 +180,7 @@ const roundedWithTitle = (parent, node) => { .attr('width', width + padding) .attr('height', node.height + padding - bbox.height - 3); + const { subGraphTitleTopMargin } = getSubGraphTitleMargins(siteConfig); // Center the label label.attr( 'transform', @@ -184,7 +190,8 @@ const roundedWithTitle = (parent, node) => { (node.y - node.height / 2 - node.padding / 3 + - (evaluate(getConfig().flowchart.htmlLabels) ? 5 : 3)) + + (evaluate(siteConfig.flowchart.htmlLabels) ? 5 : 3)) + + subGraphTitleTopMargin + ')' ); diff --git a/packages/mermaid/src/dagre-wrapper/edges.js b/packages/mermaid/src/dagre-wrapper/edges.js index c3ae81468..368390128 100644 --- a/packages/mermaid/src/dagre-wrapper/edges.js +++ b/packages/mermaid/src/dagre-wrapper/edges.js @@ -6,6 +6,7 @@ import { getConfig } from '../diagram-api/diagramAPI.js'; import utils from '../utils.js'; import { evaluate } from '../diagrams/common/common.js'; import { getLineFunctionsWithOffset } from '../utils/lineWithOffset.js'; +import { getSubGraphTitleMargins } from '../utils/subGraphTitleMargins.js'; import { addEdgeMarkers } from './edgeMarker.js'; let edgeLabels = {}; @@ -136,6 +137,8 @@ function setTerminalWidth(fo, value) { export const positionEdgeLabel = (edge, paths) => { log.info('Moving label abc78 ', edge.id, edge.label, edgeLabels[edge.id]); let path = paths.updatedPath ? paths.updatedPath : paths.originalPath; + const siteConfig = getConfig(); + const { subGraphTitleTotalMargin } = getSubGraphTitleMargins(siteConfig); if (edge.label) { const el = edgeLabels[edge.id]; let x = edge.x; @@ -159,7 +162,7 @@ export const positionEdgeLabel = (edge, paths) => { y = pos.y; } } - el.attr('transform', 'translate(' + x + ', ' + y + ')'); + el.attr('transform', `translate(${x}, ${y + subGraphTitleTotalMargin / 2})`); } //let path = paths.updatedPath ? paths.updatedPath : paths.originalPath; @@ -173,7 +176,7 @@ export const positionEdgeLabel = (edge, paths) => { x = pos.x; y = pos.y; } - el.attr('transform', 'translate(' + x + ', ' + y + ')'); + el.attr('transform', `translate(${x}, ${y})`); } if (edge.startLabelRight) { const el = terminalLabels[edge.id].startRight; @@ -189,7 +192,7 @@ export const positionEdgeLabel = (edge, paths) => { x = pos.x; y = pos.y; } - el.attr('transform', 'translate(' + x + ', ' + y + ')'); + el.attr('transform', `translate(${x}, ${y})`); } if (edge.endLabelLeft) { const el = terminalLabels[edge.id].endLeft; @@ -201,7 +204,7 @@ export const positionEdgeLabel = (edge, paths) => { x = pos.x; y = pos.y; } - el.attr('transform', 'translate(' + x + ', ' + y + ')'); + el.attr('transform', `translate(${x}, ${y})`); } if (edge.endLabelRight) { const el = terminalLabels[edge.id].endRight; @@ -213,7 +216,7 @@ export const positionEdgeLabel = (edge, paths) => { x = pos.x; y = pos.y; } - el.attr('transform', 'translate(' + x + ', ' + y + ')'); + el.attr('transform', `translate(${x}, ${y})`); } }; diff --git a/packages/mermaid/src/dagre-wrapper/index.js b/packages/mermaid/src/dagre-wrapper/index.js index 9843adb8b..76685dd7b 100644 --- a/packages/mermaid/src/dagre-wrapper/index.js +++ b/packages/mermaid/src/dagre-wrapper/index.js @@ -13,8 +13,10 @@ import { insertNode, positionNode, clear as clearNodes, setNodeElem } from './no import { insertCluster, clear as clearClusters } from './clusters.js'; import { insertEdgeLabel, positionEdgeLabel, insertEdge, clear as clearEdges } from './edges.js'; import { log } from '../logger.js'; +import { getSubGraphTitleMargins } from '../utils/subGraphTitleMargins.js'; +import { getConfig } from '../diagram-api/diagramAPI.js'; -const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => { +const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster, siteConfig) => { log.info('Graph in recursive render: XXX', graphlibJson.write(graph), parentCluster); const dir = graph.graph().rankdir; log.trace('Dir in recursive render - dir:', dir); @@ -52,7 +54,14 @@ const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => if (node && node.clusterNode) { // const children = graph.children(v); log.info('Cluster identified', v, node.width, graph.node(v)); - const o = await recursiveRender(nodes, node.graph, diagramtype, id, graph.node(v)); + const o = await recursiveRender( + nodes, + node.graph, + diagramtype, + id, + graph.node(v), + siteConfig + ); const newEl = o.elem; updateNodeBounds(node, newEl); node.diff = o.diff || 0; @@ -101,6 +110,7 @@ const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => log.info('Graph after layout:', graphlibJson.write(graph)); // Move the nodes to the correct place let diff = 0; + const { subGraphTitleTotalMargin } = getSubGraphTitleMargins(siteConfig); sortNodesByHierarchy(graph).forEach(function (v) { const node = graph.node(v); log.info('Position ' + v + ': ' + JSON.stringify(graph.node(v))); @@ -114,16 +124,18 @@ const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => ); if (node && node.clusterNode) { // clusterDb[node.id].node = node; - + node.y += subGraphTitleTotalMargin; positionNode(node); } else { // Non cluster node if (graph.children(v).length > 0) { // A cluster in the non-recursive way // positionCluster(node); + node.height += subGraphTitleTotalMargin; insertCluster(clusters, node); clusterDb[node.id].node = node; } else { + node.y += subGraphTitleTotalMargin / 2; positionNode(node); } } @@ -134,6 +146,7 @@ const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => const edge = graph.edge(e); log.info('Edge ' + e.v + ' -> ' + e.w + ': ' + JSON.stringify(edge), edge); + edge.points.forEach((point) => (point.y += subGraphTitleTotalMargin / 2)); const paths = insertEdge(edgePaths, e, edge, clusterDb, diagramtype, graph, id); positionEdgeLabel(edge, paths); }); @@ -159,7 +172,8 @@ export const render = async (elem, graph, markers, diagramtype, id) => { adjustClustersAndEdges(graph); log.warn('Graph after:', JSON.stringify(graphlibJson.write(graph))); // log.warn('Graph ever after:', graphlibJson.write(graph.node('A').graph)); - await recursiveRender(elem, graph, diagramtype, id); + const siteConfig = getConfig(); + await recursiveRender(elem, graph, diagramtype, id, undefined, siteConfig); }; // const shapeDefinitions = {}; diff --git a/packages/mermaid/src/schemas/config.schema.yaml b/packages/mermaid/src/schemas/config.schema.yaml index a51864886..f39dbe918 100644 --- a/packages/mermaid/src/schemas/config.schema.yaml +++ b/packages/mermaid/src/schemas/config.schema.yaml @@ -1869,6 +1869,7 @@ $defs: # JSON Schema definition (maybe we should move these to a separate file) unevaluatedProperties: false required: - titleTopMargin + - subGraphTitleMargin - diagramPadding - htmlLabels - nodeSpacing @@ -1881,6 +1882,20 @@ $defs: # JSON Schema definition (maybe we should move these to a separate file) titleTopMargin: $ref: '#/$defs/GitGraphDiagramConfig/properties/titleTopMargin' default: 25 + subGraphTitleMargin: + description: | + Defines a top/bottom margin for subgraph titles + type: object + properties: + top: + type: integer + minimum: 0 + bottom: + type: integer + minimum: 0 + default: + top: 0 + bottom: 0 arrowMarkerAbsolute: type: boolean # TODO, is this actually used here (it has no default value but was in types) diagramPadding: diff --git a/packages/mermaid/src/utils/subGraphTitleMargins.spec.ts b/packages/mermaid/src/utils/subGraphTitleMargins.spec.ts new file mode 100644 index 000000000..c607f8bce --- /dev/null +++ b/packages/mermaid/src/utils/subGraphTitleMargins.spec.ts @@ -0,0 +1,22 @@ +import { getSubGraphTitleMargins } from './subGraphTitleMargins.js'; +import * as configApi from '../config.js'; + +describe('getSubGraphTitleMargins', () => { + it('should get subgraph title margins after config has been set', () => { + const config_0 = { + flowchart: { + subGraphTitleMargin: { + top: 10, + bottom: 5, + }, + }, + }; + + configApi.setSiteConfig(config_0); + expect(getSubGraphTitleMargins(config_0)).toEqual({ + subGraphTitleTopMargin: 10, + subGraphTitleBottomMargin: 5, + subGraphTitleTotalMargin: 15, + }); + }); +}); diff --git a/packages/mermaid/src/utils/subGraphTitleMargins.ts b/packages/mermaid/src/utils/subGraphTitleMargins.ts new file mode 100644 index 000000000..426f4770d --- /dev/null +++ b/packages/mermaid/src/utils/subGraphTitleMargins.ts @@ -0,0 +1,21 @@ +import type { FlowchartDiagramConfig } from '../config.type.js'; + +export const getSubGraphTitleMargins = ({ + flowchart, +}: { + flowchart: FlowchartDiagramConfig; +}): { + subGraphTitleTopMargin: number; + subGraphTitleBottomMargin: number; + subGraphTitleTotalMargin: number; +} => { + const subGraphTitleTopMargin = flowchart?.subGraphTitleMargin?.top ?? 0; + const subGraphTitleBottomMargin = flowchart?.subGraphTitleMargin?.bottom ?? 0; + const subGraphTitleTotalMargin = subGraphTitleTopMargin + subGraphTitleBottomMargin; + + return { + subGraphTitleTopMargin, + subGraphTitleBottomMargin, + subGraphTitleTotalMargin, + }; +}; From 96ac2369b63f6162616cea4cae97ac6e2a742099 Mon Sep 17 00:00:00 2001 From: Matheus B Date: Tue, 16 Jan 2024 15:36:31 -0300 Subject: [PATCH 43/50] Change string concatenation to template literal --- packages/mermaid/src/dagre-wrapper/clusters.js | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/packages/mermaid/src/dagre-wrapper/clusters.js b/packages/mermaid/src/dagre-wrapper/clusters.js index 2de3f2489..cdc003e81 100644 --- a/packages/mermaid/src/dagre-wrapper/clusters.js +++ b/packages/mermaid/src/dagre-wrapper/clusters.js @@ -184,15 +184,13 @@ const roundedWithTitle = (parent, node) => { // Center the label label.attr( 'transform', - 'translate(' + - (node.x - bbox.width / 2) + - ', ' + - (node.y - - node.height / 2 - - node.padding / 3 + - (evaluate(siteConfig.flowchart.htmlLabels) ? 5 : 3)) + - subGraphTitleTopMargin + - ')' + `translate(${node.x - bbox.width / 2}, ${ + node.y - + node.height / 2 - + node.padding / 3 + + (evaluate(siteConfig.flowchart.htmlLabels) ? 5 : 3) + + subGraphTitleTopMargin + })` ); const rectBox = rect.node().getBBox(); From fb7cd9ca407c8fa68fe54ac8430e331f32cca979 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Thu, 18 Jan 2024 16:17:34 +0000 Subject: [PATCH 44/50] chore(deps): update all patch dependencies --- packages/mermaid/src/docs/package.json | 2 +- pnpm-lock.yaml | 653 +++++++------------------ 2 files changed, 179 insertions(+), 476 deletions(-) diff --git a/packages/mermaid/src/docs/package.json b/packages/mermaid/src/docs/package.json index dd33207c0..e86784212 100644 --- a/packages/mermaid/src/docs/package.json +++ b/packages/mermaid/src/docs/package.json @@ -32,7 +32,7 @@ "unplugin-vue-components": "^0.26.0", "vite": "^4.4.12", "vite-plugin-pwa": "^0.17.0", - "vitepress": "1.0.0-rc.31", + "vitepress": "1.0.0-rc.39", "workbox-window": "^7.0.0" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c0f20ed87..b9c49e0a0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -475,63 +475,8 @@ importers: specifier: ^0.17.0 version: 0.17.0(vite@4.5.0)(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 - - 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) + specifier: 1.0.0-rc.39 + version: 1.0.0-rc.39(@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 @@ -1147,10 +1092,10 @@ packages: '@babel/helper-compilation-targets': 7.22.10 '@babel/helper-module-transforms': 7.22.9(@babel/core@7.22.10) '@babel/helpers': 7.22.10 - '@babel/parser': 7.23.0 + '@babel/parser': 7.23.5 '@babel/template': 7.22.5 '@babel/traverse': 7.23.2 - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 convert-source-map: 1.9.0 debug: 4.3.4(supports-color@8.1.1) gensync: 1.0.0-beta.2 @@ -1187,7 +1132,7 @@ packages: resolution: {integrity: sha512-79KIf7YiWjjdZ81JnLujDRApWtl7BxTqWD88+FFdQEIOG8LJ0etDOM7CXuIgGJa55sGOwZVwuEsaLEm0PJ5/+A==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 '@jridgewell/gen-mapping': 0.3.3 '@jridgewell/trace-mapping': 0.3.19 jsesc: 2.5.2 @@ -1197,7 +1142,7 @@ packages: resolution: {integrity: sha512-lN85QRR+5IbYrMWM6Y4pE/noaQtg4pNiqeNGX60eqOfo6gtEj6uw/JagelB8vVztSd7R6M5n1+PQkDbHbBRU4g==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 '@jridgewell/gen-mapping': 0.3.3 '@jridgewell/trace-mapping': 0.3.19 jsesc: 2.5.2 @@ -1217,7 +1162,7 @@ packages: resolution: {integrity: sha512-LvBTxu8bQSQkcyKOU+a1btnNFQ1dMAd0R6PyW3arXes06F6QLWLIrd681bxRPIXlrMGR3XYnW9JyML7dP3qgxg==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@babel/helper-builder-binary-assignment-operator-visitor@7.22.10: @@ -1318,7 +1263,7 @@ packages: resolution: {integrity: sha512-6gfrPwh7OuT6gZyJZvd6WbTfrqAo7vm4xCzAXOusKqq/vWdKXphTpj5klHKNmRUU6/QRGlBsyU9mAIPaWHlqJA==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@babel/helper-module-imports@7.22.15: @@ -1332,7 +1277,7 @@ packages: resolution: {integrity: sha512-8Dl6+HD/cKifutF5qGd/8ZJi84QeAKh+CEe1sBzz8UayBBGg1dAIJrdHOcOM5b2MpzWL2yuotJTtGjETq0qjXg==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@babel/helper-module-transforms@7.22.9(@babel/core@7.22.10): @@ -1367,7 +1312,7 @@ packages: resolution: {integrity: sha512-HBwaojN0xFRx4yIvpwGqxiV2tUfl7401jlok564NgB9EHS1y6QT17FmKWm4ztqjeVdXLuC4fSvHc5ePpQjoTbw==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@babel/helper-plugin-utils@7.22.5: @@ -1410,7 +1355,7 @@ packages: resolution: {integrity: sha512-tK14r66JZKiC43p8Ki33yLBVJKlQDFoA8GYN67lWCDCqoL6EMMSuM9b+Iff2jHaM/RRFYl7K+iiru7hbRqNx8Q==} engines: {node: '>=6.9.0'} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@babel/helper-split-export-declaration@7.22.6: @@ -1462,7 +1407,7 @@ packages: dependencies: '@babel/template': 7.22.15 '@babel/traverse': 7.23.2 - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 transitivePeerDependencies: - supports-color dev: true @@ -1510,6 +1455,14 @@ packages: dependencies: '@babel/types': 7.23.5 + /@babel/parser@7.23.6: + resolution: {integrity: sha512-Z2uID7YJ7oNvAI20O9X0bblw7Qqs8Q2hFy0R9tAfnfLkp5MW0UH9eUvnDSnFwKZ0AvgS1ucqR4KzvVHgnke1VQ==} + engines: {node: '>=6.0.0'} + 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==} engines: {node: '>=6.9.0'} @@ -2545,8 +2498,8 @@ packages: engines: {node: '>=6.9.0'} dependencies: '@babel/code-frame': 7.22.13 - '@babel/parser': 7.23.0 - '@babel/types': 7.23.0 + '@babel/parser': 7.23.5 + '@babel/types': 7.23.5 dev: true /@babel/traverse@7.23.2: @@ -2559,8 +2512,8 @@ packages: '@babel/helper-function-name': 7.23.0 '@babel/helper-hoist-variables': 7.22.5 '@babel/helper-split-export-declaration': 7.22.6 - '@babel/parser': 7.23.0 - '@babel/types': 7.23.0 + '@babel/parser': 7.23.5 + '@babel/types': 7.23.5 debug: 4.3.4(supports-color@8.1.1) globals: 11.12.0 transitivePeerDependencies: @@ -4636,7 +4589,7 @@ packages: resolution: {integrity: sha512-aACu/U/omhdk15O4Nfb+fHgH/z3QsfQzpnvRZhYhThms83ZnAOZz7zZAWO7mn2yyNQaA4xTO8GLK3uqFU4bYYw==} dependencies: '@babel/parser': 7.23.5 - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 '@types/babel__generator': 7.6.4 '@types/babel__template': 7.4.1 '@types/babel__traverse': 7.20.1 @@ -4645,20 +4598,20 @@ packages: /@types/babel__generator@7.6.4: resolution: {integrity: sha512-tFkciB9j2K755yrTALxD44McOrk+gfpIpvC3sxHjRawj6PfnQxrse4Clq5y/Rq+G3mrBurMax/lG8Qn2t9mSsg==} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@types/babel__template@7.4.1: resolution: {integrity: sha512-azBFKemX6kMg5Io+/rdGT0dkGreboUVR0Cdm3fz9QJWpaQGJRQXl7C+6hOTCZcMll7KFyEQpgbYI2lHdsS4U7g==} dependencies: '@babel/parser': 7.23.5 - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@types/babel__traverse@7.20.1: resolution: {integrity: sha512-MitHFXnhtgwsGZWtT68URpOvLN4EREih1u3QtQiN4VdAxWKRVvGCSvw/Qth0M0Qq3pJpnGOu5JaM/ydK7OGbqg==} dependencies: - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 dev: true /@types/body-parser@1.19.2: @@ -4984,12 +4937,6 @@ packages: '@types/node': 18.17.5 dev: true - /@types/hast@3.0.3: - resolution: {integrity: sha512-2fYGlaDy/qyLlhidX42wAH0KBi2TCjKMH8CHmBXgRlJ3Y+OXTiqsPQ6IWarZKwF1JoUcAJdPogv1d4b0COTpmQ==} - dependencies: - '@types/unist': 3.0.2 - dev: true - /@types/http-cache-semantics@4.0.1: resolution: {integrity: sha512-SZs7ekbP8CN0txVG2xVRH6EgKmEm31BOxA07vkFaETzZz1xh+cbt8BcI0slpymvwhx5dlFnQG2rTlPVQn+iRPQ==} dev: true @@ -5075,12 +5022,6 @@ packages: dependencies: '@types/unist': 2.0.7 - /@types/mdast@4.0.3: - resolution: {integrity: sha512-LsjtqsyF+d2/yFOYaN22dHZI1Cpwkrj+g06G8+qtUKlhovPW89YhqSnfKtMbkgmEtYpH2gydRNULd6y8mciAFg==} - dependencies: - '@types/unist': 3.0.2 - dev: true - /@types/mdurl@1.0.2: resolution: {integrity: sha512-eC4U9MlIcu2q0KQmXszyn5Akca/0jrQmwDRgpAMJai7qBWq4amIQhZyNau4VYGtCeALvW1/NtjzJJ567aZxfKA==} dev: true @@ -5224,10 +5165,6 @@ packages: /@types/unist@2.0.7: resolution: {integrity: sha512-cputDpIbFgLUaGQn6Vqg3/YsJwxUwHLO13v3i5ouxT4lat0khip9AEWxtERujXV9wxIB1EyF97BSJFt6vpdI8g==} - /@types/unist@3.0.2: - resolution: {integrity: sha512-dqId9J8K/vGi5Zr7oo212BGii5m3q5Hxlkwy3WpYuKPklmBEvsbMYYyLxAQpSffdLl/gdW0XUpKWFvYmyoWCoQ==} - dev: true - /@types/uuid@9.0.1: resolution: {integrity: sha512-rFT3ak0/2trgvp4yYZo5iKFEPsET7vKydKF+VRCxlQ9bpheehyAJH89dAkaLEq/j/RZXJIqcgsmPJKUP1Z28HA==} dev: true @@ -5591,26 +5528,6 @@ packages: eslint-visitor-keys: 3.4.3 dev: true - /@ungap/structured-clone@1.2.0: - 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: @@ -5805,26 +5722,6 @@ 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: @@ -5850,18 +5747,7 @@ packages: peerDependencies: vite-plugin-pwa: '>=0.17.0 <1' dependencies: - 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 + vite-plugin-pwa: 0.17.0(vite@4.5.0)(workbox-build@7.0.0)(workbox-window@7.0.0) dev: true /@vitejs/plugin-vue@4.2.1(vite@4.5.0)(vue@3.3.4): @@ -5886,15 +5772,15 @@ packages: vue: 3.3.4 dev: true - /@vitejs/plugin-vue@4.5.0(vite@5.0.2)(vue@3.3.8): - resolution: {integrity: sha512-a2WSpP8X8HTEww/U00bU4mX1QpLINNuz/2KMNpLsdu3BzOpak3AGI1CJYBTXcc4SPhaD0eNRUp7IyQK405L5dQ==} - engines: {node: ^14.18.0 || >=16.0.0} + /@vitejs/plugin-vue@5.0.3(vite@5.0.11)(vue@3.4.15): + resolution: {integrity: sha512-b8S5dVS40rgHdDrw+DQi/xOM9ed+kSRZzfm1T74bMmBDCd8XO87NKlFYInzCtwvtWwXZvo1QxE2OSspTATWrbA==} + engines: {node: ^18.0.0 || >=20.0.0} peerDependencies: - vite: ^4.0.0 || ^5.0.0 + vite: ^5.0.0 vue: ^3.2.25 dependencies: - vite: 5.0.2(@types/node@18.17.5) - vue: 3.3.8(typescript@5.1.6) + vite: 5.0.11(@types/node@18.17.5) + vue: 3.4.15(typescript@5.1.6) dev: true /@vitest/coverage-v8@0.34.0(vitest@0.34.0): @@ -5999,6 +5885,16 @@ packages: source-map-js: 1.0.2 dev: true + /@vue/compiler-core@3.4.15: + resolution: {integrity: sha512-XcJQVOaxTKCnth1vCxEChteGuwG6wqnUHxAm1DO3gCz0+uXKaJNx8/digSz4dLALCy8n2lKq24jSUs8segoqIw==} + dependencies: + '@babel/parser': 7.23.6 + '@vue/shared': 3.4.15 + entities: 4.5.0 + estree-walker: 2.0.2 + source-map-js: 1.0.2 + dev: true + /@vue/compiler-dom@3.3.4: resolution: {integrity: sha512-wyM+OjOVpuUukIq6p5+nwHYtj9cFroz9cwkfmP9O1nzH68BenTTv0u7/ndggT8cIQlnBeOo6sUT/gvHcIkLA5w==} dependencies: @@ -6012,6 +5908,13 @@ packages: '@vue/shared': 3.3.8 dev: true + /@vue/compiler-dom@3.4.15: + resolution: {integrity: sha512-wox0aasVV74zoXyblarOM3AZQz/Z+OunYcIHe1OsGclCHt8RsRm04DObjefaI82u6XDzv+qGWZ24tIsRAIi5MQ==} + dependencies: + '@vue/compiler-core': 3.4.15 + '@vue/shared': 3.4.15 + dev: true + /@vue/compiler-sfc@3.3.4: resolution: {integrity: sha512-6y/d8uw+5TkCuzBkgLS0v3lSM3hJDntFEiUORM11pQ/hKvkhSKZrXW6i69UyXlJQisJxuUEJKAWEqWbWsLeNKQ==} dependencies: @@ -6041,6 +5944,20 @@ packages: source-map-js: 1.0.2 dev: true + /@vue/compiler-sfc@3.4.15: + resolution: {integrity: sha512-LCn5M6QpkpFsh3GQvs2mJUOAlBQcCco8D60Bcqmf3O3w5a+KWS5GvYbrrJBkgvL1BDnTp+e8q0lXCLgHhKguBA==} + dependencies: + '@babel/parser': 7.23.6 + '@vue/compiler-core': 3.4.15 + '@vue/compiler-dom': 3.4.15 + '@vue/compiler-ssr': 3.4.15 + '@vue/shared': 3.4.15 + estree-walker: 2.0.2 + magic-string: 0.30.5 + postcss: 8.4.33 + source-map-js: 1.0.2 + dev: true + /@vue/compiler-ssr@3.3.4: resolution: {integrity: sha512-m0v6oKpup2nMSehwA6Uuu+j+wEwcy7QmwMkVNVfrV9P2qE5KshC6RwOCq8fjGS/Eak/uNb8AaWekfiXxbBB6gQ==} dependencies: @@ -6054,6 +5971,13 @@ packages: '@vue/shared': 3.3.8 dev: true + /@vue/compiler-ssr@3.4.15: + resolution: {integrity: sha512-1jdeQyiGznr8gjFDadVmOJqZiLNSsMa5ZgqavkPZ8O2wjHv0tVuAEsw5hTdUoUW4232vpBbL/wJhzVW/JwY1Uw==} + dependencies: + '@vue/compiler-dom': 3.4.15 + '@vue/shared': 3.4.15 + dev: true + /@vue/devtools-api@6.5.0: resolution: {integrity: sha512-o9KfBeaBmCKl10usN4crU53fYtC1r7jJwdGKjPT24t348rHxgfpZ0xL3Xm/gLUYnc0oTp8LAmrxOeLyu6tbk2Q==} dev: true @@ -6091,6 +6015,12 @@ packages: '@vue/shared': 3.3.8 dev: true + /@vue/reactivity@3.4.15: + resolution: {integrity: sha512-55yJh2bsff20K5O84MxSvXKPHHt17I2EomHznvFiJCAZpJTNW8IuLj1xZWMLELRhBK3kkFV/1ErZGHJfah7i7w==} + dependencies: + '@vue/shared': 3.4.15 + dev: true + /@vue/runtime-core@3.3.4: resolution: {integrity: sha512-R+bqxMN6pWO7zGI4OMlmvePOdP2c93GsHFM/siJI7O2nxFRzj55pLwkpCedEY+bTMgp5miZ8CxfIZo3S+gFqvA==} dependencies: @@ -6104,6 +6034,13 @@ packages: '@vue/shared': 3.3.8 dev: true + /@vue/runtime-core@3.4.15: + resolution: {integrity: sha512-6E3by5m6v1AkW0McCeAyhHTw+3y17YCOKG0U0HDKDscV4Hs0kgNT5G+GCHak16jKgcCDHpI9xe5NKb8sdLCLdw==} + dependencies: + '@vue/reactivity': 3.4.15 + '@vue/shared': 3.4.15 + dev: true + /@vue/runtime-dom@3.3.4: resolution: {integrity: sha512-Aj5bTJ3u5sFsUckRghsNjVTtxZQ1OyMWCr5dZRAPijF/0Vy4xEoRCwLyHXcj4D0UFbJ4lbx3gPTgg06K/GnPnQ==} dependencies: @@ -6119,6 +6056,14 @@ packages: csstype: 3.1.2 dev: true + /@vue/runtime-dom@3.4.15: + resolution: {integrity: sha512-EVW8D6vfFVq3V/yDKNPBFkZKGMFSvZrUQmx196o/v2tHKdwWdiZjYUBS+0Ez3+ohRyF8Njwy/6FH5gYJ75liUw==} + dependencies: + '@vue/runtime-core': 3.4.15 + '@vue/shared': 3.4.15 + csstype: 3.1.3 + dev: true + /@vue/server-renderer@3.3.4(vue@3.3.4): resolution: {integrity: sha512-Q6jDDzR23ViIb67v+vM1Dqntu+HUexQcsWKhhQa4ARVzxOY2HbC7QRW/ggkDBd5BU+uM1sV6XOAP0b216o34JQ==} peerDependencies: @@ -6138,6 +6083,16 @@ packages: vue: 3.3.8(typescript@5.0.4) dev: true + /@vue/server-renderer@3.4.15(vue@3.4.15): + resolution: {integrity: sha512-3HYzaidu9cHjrT+qGUuDhFYvF/j643bHC6uUN9BgM11DVy+pM6ATsG6uPBLnkwOgs7BpJABReLmpL3ZPAsUaqw==} + peerDependencies: + vue: 3.4.15 + dependencies: + '@vue/compiler-ssr': 3.4.15 + '@vue/shared': 3.4.15 + vue: 3.4.15(typescript@5.1.6) + dev: true + /@vue/shared@3.3.4: resolution: {integrity: sha512-7OjdcV8vQ74eiz1TZLzZP4JwqM5fA94K6yntPS5Z25r9HDuGNzaGdgvwKYq6S+MxwF0TFRwe50fIR/MYnakdkQ==} @@ -6145,6 +6100,10 @@ packages: resolution: {integrity: sha512-8PGwybFwM4x8pcfgqEQFy70NaQxASvOC5DJwLQfpArw1UDfUXrJkdxD3BhVTMS+0Lef/TU7YO0Jvr0jJY8T+mw==} dev: true + /@vue/shared@3.4.15: + resolution: {integrity: sha512-KzfPTxVaWfB+eGcGdbSf4CWdaXcGDqckoeXUh7SB3fZdEtzPCK2Vq9B/lRRL3yutax/LWITz+SwvgyOxz5V75g==} + dev: true + /@vueuse/core@10.1.0(vue@3.3.4): resolution: {integrity: sha512-3Znoa5m5RO+z4/C9w6DRaKTR3wCVJvD5rav8HTDGsr+7rOZRHtcgFJ8NcCs0ZvIpmev2kExTa311ns5j2RbzDQ==} dependencies: @@ -6169,20 +6128,20 @@ packages: - vue dev: true - /@vueuse/core@10.6.1(vue@3.3.8): - resolution: {integrity: sha512-Pc26IJbqgC9VG1u6VY/xrXXfxD33hnvxBnKrLlA2LJlyHII+BSrRoTPJgGYq7qZOu61itITFUnm6QbacwZ4H8Q==} + /@vueuse/core@10.7.2(vue@3.4.15): + resolution: {integrity: sha512-AOyAL2rK0By62Hm+iqQn6Rbu8bfmbgaIMXcE3TSr7BdQ42wnSFlwIdPjInO62onYsEMK/yDMU8C6oGfDAtZ2qQ==} dependencies: '@types/web-bluetooth': 0.0.20 - '@vueuse/metadata': 10.6.1 - '@vueuse/shared': 10.6.1(vue@3.3.8) - vue-demi: 0.14.6(vue@3.3.8) + '@vueuse/metadata': 10.7.2 + '@vueuse/shared': 10.7.2(vue@3.4.15) + vue-demi: 0.14.6(vue@3.4.15) transitivePeerDependencies: - '@vue/composition-api' - vue dev: true - /@vueuse/integrations@10.6.1(focus-trap@7.5.4)(vue@3.3.8): - resolution: {integrity: sha512-mPDupuofMJ4DPmtX/FfP1MajmWRzYDv8WSaTCo8LQ5kFznjWgmUQ16ApjYqgMquqffNY6+IRMdMgosLDRZOSZA==} + /@vueuse/integrations@10.7.2(focus-trap@7.5.4)(vue@3.4.15): + resolution: {integrity: sha512-+u3RLPFedjASs5EKPc69Ge49WNgqeMfSxFn+qrQTzblPXZg6+EFzhjarS5edj2qAf6xQ93f95TUxRwKStXj/sQ==} peerDependencies: async-validator: '*' axios: '*' @@ -6222,10 +6181,10 @@ packages: universal-cookie: optional: true dependencies: - '@vueuse/core': 10.6.1(vue@3.3.8) - '@vueuse/shared': 10.6.1(vue@3.3.8) + '@vueuse/core': 10.7.2(vue@3.4.15) + '@vueuse/shared': 10.7.2(vue@3.4.15) focus-trap: 7.5.4 - vue-demi: 0.14.6(vue@3.3.8) + vue-demi: 0.14.6(vue@3.4.15) transitivePeerDependencies: - '@vue/composition-api' - vue @@ -6239,8 +6198,8 @@ packages: resolution: {integrity: sha512-Ema3YhNOa4swDsV0V7CEY5JXvK19JI/o1szFO1iWxdFg3vhdFtCtSTP26PCvbUpnUtNHBY2wx5y3WDXND5Pvnw==} dev: true - /@vueuse/metadata@10.6.1: - resolution: {integrity: sha512-qhdwPI65Bgcj23e5lpGfQsxcy0bMjCAsUGoXkJ7DsoeDUdasbZ2DBa4dinFCOER3lF4gwUv+UD2AlA11zdzMFw==} + /@vueuse/metadata@10.7.2: + resolution: {integrity: sha512-kCWPb4J2KGrwLtn1eJwaJD742u1k5h6v/St5wFe8Quih90+k2a0JP8BS4Zp34XUuJqS2AxFYMb1wjUL8HfhWsQ==} dev: true /@vueuse/shared@10.1.0(vue@3.3.4): @@ -6261,10 +6220,10 @@ packages: - vue dev: true - /@vueuse/shared@10.6.1(vue@3.3.8): - resolution: {integrity: sha512-TECVDTIedFlL0NUfHWncf3zF9Gc4VfdxfQc8JFwoVZQmxpONhLxFrlm0eHQeidHj4rdTPL3KXJa0TZCk1wnc5Q==} + /@vueuse/shared@10.7.2(vue@3.4.15): + resolution: {integrity: sha512-qFbXoxS44pi2FkgFjPvF4h7c9oMDutpyBdcJdMYIMg9XyXli2meFMuaKn+UMgsClo//Th6+beeCgqweT/79BVA==} dependencies: - vue-demi: 0.14.6(vue@3.3.8) + vue-demi: 0.14.6(vue@3.4.15) transitivePeerDependencies: - '@vue/composition-api' - vue @@ -6990,7 +6949,7 @@ packages: engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} dependencies: '@babel/template': 7.22.15 - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 '@types/babel__core': 7.20.1 '@types/babel__traverse': 7.20.1 dev: true @@ -7433,18 +7392,10 @@ packages: engines: {node: '>=10'} dev: true - /character-entities-html4@2.1.0: - resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==} - dev: true - /character-entities-legacy@1.1.4: resolution: {integrity: sha512-3Xnr+7ZFS1uxeiUDvV02wQ+QDbc55o97tIV5zHScSPJpcLm/r0DFPcoY3tYRp+VZukxuMeKgXYmsXQHO05zQeA==} dev: true - /character-entities-legacy@3.0.0: - resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==} - dev: true - /character-entities@1.2.4: resolution: {integrity: sha512-iBMyeEHxfVnIakwOuDXpVkc54HijNgCyQB2w0VfGQThle6NXn50zU6V/u+LDhxHcDUPojn6Kpga3PTAD8W1bQw==} dev: true @@ -7666,10 +7617,6 @@ packages: delayed-stream: 1.0.0 dev: true - /comma-separated-tokens@2.0.3: - resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==} - dev: true - /commander@10.0.1: resolution: {integrity: sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==} engines: {node: '>=14'} @@ -8230,6 +8177,10 @@ packages: /csstype@3.1.2: resolution: {integrity: sha512-I7K1Uu0MBPzaFKg4nI5Q7Vs2t+3gWWW648spaF+Rg7pI9ds18Ugn+lvg4SHczUdKlHI5LWBXyqfS8+DufyBsgQ==} + /csstype@3.1.3: + resolution: {integrity: sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==} + dev: true + /cuint@0.2.2: resolution: {integrity: sha512-d4ZVpCW31eWwCMe1YT3ur7mUDnTXbgwyzaL320DrcRT45rfjYxkt5QWLrmOJ+/UEAI2+fQgKe/fCjR8l4TpRgw==} dev: true @@ -8949,12 +8900,6 @@ packages: resolution: {integrity: sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==} dev: true - /devlop@1.1.0: - resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} - dependencies: - dequal: 2.0.3 - dev: true - /didyoumean@1.2.2: resolution: {integrity: sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==} dev: false @@ -10730,88 +10675,6 @@ packages: type-fest: 0.8.1 dev: true - /hast-util-from-parse5@8.0.1: - resolution: {integrity: sha512-Er/Iixbc7IEa7r/XLtuG52zoqn/b3Xng/w6aZQ0xGVxzhw5xUFxcRqdPzP6yFi/4HBYRaifaI5fQ1RH8n0ZeOQ==} - dependencies: - '@types/hast': 3.0.3 - '@types/unist': 3.0.2 - devlop: 1.1.0 - hastscript: 8.0.0 - property-information: 6.4.0 - vfile: 6.0.1 - vfile-location: 5.0.2 - web-namespaces: 2.0.1 - dev: true - - /hast-util-parse-selector@4.0.0: - resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==} - dependencies: - '@types/hast': 3.0.3 - dev: true - - /hast-util-raw@9.0.1: - resolution: {integrity: sha512-5m1gmba658Q+lO5uqL5YNGQWeh1MYWZbZmWrM5lncdcuiXuo5E2HT/CIOp0rLF8ksfSwiCVJ3twlgVRyTGThGA==} - dependencies: - '@types/hast': 3.0.3 - '@types/unist': 3.0.2 - '@ungap/structured-clone': 1.2.0 - hast-util-from-parse5: 8.0.1 - hast-util-to-parse5: 8.0.0 - html-void-elements: 3.0.0 - mdast-util-to-hast: 13.0.2 - parse5: 7.1.2 - unist-util-position: 5.0.0 - unist-util-visit: 5.0.0 - vfile: 6.0.1 - web-namespaces: 2.0.1 - zwitch: 2.0.4 - dev: true - - /hast-util-to-html@9.0.0: - resolution: {integrity: sha512-IVGhNgg7vANuUA2XKrT6sOIIPgaYZnmLx3l/CCOAK0PtgfoHrZwX7jCSYyFxHTrGmC6S9q8aQQekjp4JPZF+cw==} - dependencies: - '@types/hast': 3.0.3 - '@types/unist': 3.0.2 - ccount: 2.0.1 - comma-separated-tokens: 2.0.3 - hast-util-raw: 9.0.1 - hast-util-whitespace: 3.0.0 - html-void-elements: 3.0.0 - mdast-util-to-hast: 13.0.2 - property-information: 6.4.0 - space-separated-tokens: 2.0.2 - stringify-entities: 4.0.3 - zwitch: 2.0.4 - dev: true - - /hast-util-to-parse5@8.0.0: - resolution: {integrity: sha512-3KKrV5ZVI8if87DVSi1vDeByYrkGzg4mEfeu4alwgmmIeARiBLKCZS2uw5Gb6nU9x9Yufyj3iudm6i7nl52PFw==} - dependencies: - '@types/hast': 3.0.3 - comma-separated-tokens: 2.0.3 - devlop: 1.1.0 - property-information: 6.4.0 - space-separated-tokens: 2.0.2 - web-namespaces: 2.0.1 - zwitch: 2.0.4 - dev: true - - /hast-util-whitespace@3.0.0: - resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==} - dependencies: - '@types/hast': 3.0.3 - dev: true - - /hastscript@8.0.0: - resolution: {integrity: sha512-dMOtzCEd3ABUeSIISmrETiKuyydk1w0pa+gE/uormcTpSYuaNJPbX1NU3JLyscSLjwAQM8bWMhhIlnCqnRvDTw==} - dependencies: - '@types/hast': 3.0.3 - comma-separated-tokens: 2.0.3 - hast-util-parse-selector: 4.0.0 - property-information: 6.4.0 - space-separated-tokens: 2.0.2 - dev: true - /heap@0.2.7: resolution: {integrity: sha512-2bsegYkkHO+h/9MGbn6KWcE45cHZgPANo5LXF7EvWdT0yT2EguSVO1nDgU5c8+ZOPwp2vMNa7YFsJhVcDR9Sdg==} dev: false @@ -10859,10 +10722,6 @@ packages: resolution: {integrity: sha512-9gux8QhvjRO/erSnDPv28noDZcPZmYE7e1vFsBLKLlRlKDSqNJYebj6Qz1TGd5lsRV+X+xYyjCKjuZdABinWjA==} dev: false - /html-void-elements@3.0.0: - resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} - dev: true - /htmlparser2@8.0.2: resolution: {integrity: sha512-GYdjWKDkbRLkZ5geuHs5NY1puJ+PXwP7+fHPRz06Eirsb9ugf6d8kkXav6ADhcODhFFPMIXyxkxSuMf3D6NCFA==} dependencies: @@ -11903,7 +11762,7 @@ packages: '@babel/generator': 7.23.0 '@babel/plugin-syntax-jsx': 7.22.5(@babel/core@7.22.10) '@babel/plugin-syntax-typescript': 7.22.5(@babel/core@7.22.10) - '@babel/types': 7.23.0 + '@babel/types': 7.23.5 '@jest/expect-utils': 29.6.2 '@jest/transform': 29.6.2 '@jest/types': 29.6.1 @@ -12838,19 +12697,6 @@ packages: unist-util-is: 5.2.1 dev: true - /mdast-util-to-hast@13.0.2: - resolution: {integrity: sha512-U5I+500EOOw9e3ZrclN3Is3fRpw8c19SMyNZlZ2IS+7vLsNzb2Om11VpIVOR+/0137GhZsFEF6YiKD5+0Hr2Og==} - dependencies: - '@types/hast': 3.0.3 - '@types/mdast': 4.0.3 - '@ungap/structured-clone': 1.2.0 - devlop: 1.1.0 - micromark-util-sanitize-uri: 2.0.0 - trim-lines: 3.0.1 - unist-util-position: 5.0.0 - unist-util-visit: 5.0.0 - dev: true - /mdast-util-to-markdown@1.5.0: resolution: {integrity: sha512-bbv7TPv/WC49thZPg3jXuqzuvI45IL2EVAr/KxF0BSdHsU0ceFHOmwQn6evxAh1GaoK/6GQ1wp4R4oW2+LFL/A==} dependencies: @@ -13106,13 +12952,6 @@ packages: micromark-util-symbol: 1.1.0 micromark-util-types: 1.1.0 - /micromark-util-character@2.0.1: - resolution: {integrity: sha512-3wgnrmEAJ4T+mGXAUfMvMAbxU9RDG43XmGce4j6CwPtVxB3vfwXSZ6KhFwDzZ3mZHhmPimMAXg71veiBGzeAZw==} - dependencies: - micromark-util-symbol: 2.0.0 - micromark-util-types: 2.0.0 - dev: true - /micromark-util-chunked@1.1.0: resolution: {integrity: sha512-Ye01HXpkZPNcV6FiyoW2fGZDUw4Yc7vT0E9Sad83+bEDiCJ1uXu0S3mr8WLpsz3HaG3x2q0HM6CTuPdcZcluFQ==} dependencies: @@ -13147,10 +12986,6 @@ packages: /micromark-util-encode@1.1.0: resolution: {integrity: sha512-EuEzTWSTAj9PA5GOAs992GzNh2dGQO52UvAbtSOMvXTxv3Criqb6IOzJUBCmEqrrXSblJIJBbFFv6zPxpreiJw==} - /micromark-util-encode@2.0.0: - resolution: {integrity: sha512-pS+ROfCXAGLWCOc8egcBvT0kf27GoWMqtdarNfDcjb6YLuV5cM3ioG45Ys2qOVqeqSbjaKg72vU+Wby3eddPsA==} - dev: true - /micromark-util-html-tag-name@1.2.0: resolution: {integrity: sha512-VTQzcuQgFUD7yYztuQFKXT49KghjtETQ+Wv/zUjGSGBioZnkA4P1XXZPT1FHeJA6RwRXSF47yvJ1tsJdoxwO+Q==} @@ -13171,14 +13006,6 @@ packages: micromark-util-encode: 1.1.0 micromark-util-symbol: 1.1.0 - /micromark-util-sanitize-uri@2.0.0: - resolution: {integrity: sha512-WhYv5UEcZrbAtlsnPuChHUAsu/iBPOVaEVsntLBIdpibO0ddy8OzavZz3iL2xVvBZOpolujSliP65Kq0/7KIYw==} - dependencies: - micromark-util-character: 2.0.1 - micromark-util-encode: 2.0.0 - micromark-util-symbol: 2.0.0 - dev: true - /micromark-util-subtokenize@1.1.0: resolution: {integrity: sha512-kUQHyzRoxvZO2PuLzMt2P/dwVsTiivCK8icYTeR+3WgbuPqfHgPPy7nFKbeqRivBvn/3N3GBiNC+JRTMSxEC7A==} dependencies: @@ -13190,17 +13017,9 @@ packages: /micromark-util-symbol@1.1.0: resolution: {integrity: sha512-uEjpEYY6KMs1g7QfJ2eX1SQEV+ZT4rUD3UcF6l57acZvLNK7PBZL+ty82Z1qhK1/yXIY4bdx04FKMgR0g4IAag==} - /micromark-util-symbol@2.0.0: - resolution: {integrity: sha512-8JZt9ElZ5kyTnO94muPxIGS8oyElRJaiJO8EzV6ZSyGQ1Is8xwl4Q45qU5UOg+bGH4AikWziz0iN4sFLWs8PGw==} - dev: true - /micromark-util-types@1.1.0: resolution: {integrity: sha512-ukRBgie8TIAcacscVHSiddHjO4k/q3pnedmzMQ4iwDcK0FtFCohKOlFbaOL/mPgfnPsL3C1ZyxJa4sbWrBl3jg==} - /micromark-util-types@2.0.0: - resolution: {integrity: sha512-oNh6S2WMHWRZrmutsRmDDfkzKtxF+bc2VxLC9dvtrDIRFln627VsFP6fLMgTryGDljgLPjkrzQSDcPrjPyDJ5w==} - dev: true - /micromark@2.11.4: resolution: {integrity: sha512-+WoovN/ppKolQOFIAajxi7Lu9kInbPxFuTBVEavFcL8eAfVstoc5MocPmqBeAdBOJV00uaVjegzH4+MA0DN/uA==} dependencies: @@ -13394,6 +13213,12 @@ packages: engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} hasBin: true + /nanoid@3.3.7: + resolution: {integrity: sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==} + engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} + hasBin: true + dev: true + /natural-compare-lite@1.4.0: resolution: {integrity: sha512-Tj+HTDSJJKaZnfiuw+iaF9skdPpTo2GtEly5JHnWV/hfv2Qj/9RKsGISQtLh2ox3l5EAGw487hnBee0sIJ6v2g==} dev: true @@ -14205,6 +14030,15 @@ packages: picocolors: 1.0.0 source-map-js: 1.0.2 + /postcss@8.4.33: + resolution: {integrity: sha512-Kkpbhhdjw2qQs2O2DGX+8m5OVqEcbB9HRBvuYM9pgrjEFUg30A9LmXNlTAUj4S9kgtGyrMbTzVjH7E+s5Re2yg==} + engines: {node: ^10 || ^12 || >=14} + dependencies: + nanoid: 3.3.7 + picocolors: 1.0.0 + source-map-js: 1.0.2 + dev: true + /preact@10.16.0: resolution: {integrity: sha512-XTSj3dJ4roKIC93pald6rWuB2qQJO9gO2iLLyTe87MrjQN+HklueLsmskbywEWqCHlclgz3/M4YLL2iBr9UmMA==} dev: true @@ -14285,10 +14119,6 @@ packages: sisteransi: 1.0.5 dev: true - /property-information@6.4.0: - resolution: {integrity: sha512-9t5qARVofg2xQqKtytzt+lZ4d1Qvj8t5B8fEwXK6qOfgRLgH/b13QlgEyDh033NOS31nXeFbYv7CLUDG1CeifQ==} - dev: true - /proxy-addr@2.0.7: resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==} engines: {node: '>= 0.10'} @@ -15121,16 +14951,20 @@ packages: vscode-textmate: 8.0.0 dev: true - /shikiji-transformers@0.7.4: - resolution: {integrity: sha512-oykilNekcW2FnRGbvZm+RNWHYroSeCVMOaMMwAbxozZgpTdcJtHoA+1+MDFw6/o2hCkX88kKbxG6FwAZoUZ6WQ==} - dependencies: - shikiji: 0.7.4 + /shikiji-core@0.9.19: + resolution: {integrity: sha512-AFJu/vcNT21t0e6YrfadZ+9q86gvPum6iywRyt1OtIPjPFe25RQnYJyxHQPMLKCCWA992TPxmEmbNcOZCAJclw==} dev: true - /shikiji@0.7.4: - resolution: {integrity: sha512-N5dmPvyhH/zfcsuWysUEAMwRJDMz26LUns2VEUs5y4Ozbf5jkAODU0Yswjcf/tZAwpFnk5x3y34dupFMnF2+NA==} + /shikiji-transformers@0.9.19: + resolution: {integrity: sha512-lGLI7Z8frQrIBbhZ74/eiJtxMoCQRbpaHEB+gcfvdIy+ZFaAtXncJGnc52932/UET+Y4GyKtwwC/vjWUCp+c/Q==} dependencies: - hast-util-to-html: 9.0.0 + shikiji: 0.9.19 + dev: true + + /shikiji@0.9.19: + resolution: {integrity: sha512-Kw2NHWktdcdypCj1GkKpXH4o6Vxz8B8TykPlPuLHOGSV8VkhoCLcFOH4k19K4LXAQYRQmxg+0X/eM+m2sLhAkg==} + dependencies: + shikiji-core: 0.9.19 dev: true /side-channel@1.0.4: @@ -15279,10 +15113,6 @@ packages: deprecated: Please use @jridgewell/sourcemap-codec instead dev: true - /space-separated-tokens@2.0.2: - resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==} - dev: true - /spawn-command@0.0.2-1: resolution: {integrity: sha512-n98l9E2RMSJ9ON1AKisHzz7V42VDiBQGY6PB1BwRglz99wpVsSuGzQ+jOi6lFXBGVTCrRpltvjm+/XA+tpeJrg==} dev: true @@ -15521,13 +15351,6 @@ packages: dependencies: safe-buffer: 5.2.1 - /stringify-entities@4.0.3: - resolution: {integrity: sha512-BP9nNHMhhfcMbiuQKCqMjhDP5yBCAxsPu4pHFFzJ6Alo9dZgY4VLDPutXqIjpRiMoKdp7Av85Gr73Q5uH9k7+g==} - dependencies: - character-entities-html4: 2.1.0 - character-entities-legacy: 3.0.0 - dev: true - /stringify-object@3.3.0: resolution: {integrity: sha512-rHqiFh1elqCQ9WPLIC8I0Q/g/wj5J1eMkyoiD6eoQApWHP0FtlK7rqnhmabL5VUY9JQCcqwwvlOaSuutekgyrw==} engines: {node: '>=4'} @@ -15940,10 +15763,6 @@ packages: hasBin: true dev: true - /trim-lines@3.0.1: - resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==} - dev: true - /trim-newlines@3.0.1: resolution: {integrity: sha512-c1PTsA3tYrIsLGkJkzHF+w9F2EyxfXGo4UyJc4pFL++FMjnq0HJS69T3M7d//gKrFKwy429bouPescbjecU+Zw==} engines: {node: '>=8'} @@ -16315,18 +16134,6 @@ packages: '@types/unist': 2.0.7 dev: true - /unist-util-is@6.0.0: - resolution: {integrity: sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==} - dependencies: - '@types/unist': 3.0.2 - dev: true - - /unist-util-position@5.0.0: - resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==} - dependencies: - '@types/unist': 3.0.2 - dev: true - /unist-util-stringify-position@2.0.3: resolution: {integrity: sha512-3faScn5I+hy9VleOq/qNbAd6pAx7iH5jYBMS9I1HgQVijz/4mv5Bvw5iw1sC/90CODiKo81G/ps8AJrISn687g==} dependencies: @@ -16338,12 +16145,6 @@ packages: dependencies: '@types/unist': 2.0.7 - /unist-util-stringify-position@4.0.0: - resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==} - dependencies: - '@types/unist': 3.0.2 - dev: true - /unist-util-visit-parents@5.1.3: resolution: {integrity: sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==} dependencies: @@ -16351,13 +16152,6 @@ packages: unist-util-is: 5.2.1 dev: true - /unist-util-visit-parents@6.0.1: - resolution: {integrity: sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==} - dependencies: - '@types/unist': 3.0.2 - unist-util-is: 6.0.0 - dev: true - /unist-util-visit@4.1.2: resolution: {integrity: sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==} dependencies: @@ -16366,14 +16160,6 @@ packages: unist-util-visit-parents: 5.1.3 dev: true - /unist-util-visit@5.0.0: - resolution: {integrity: sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==} - dependencies: - '@types/unist': 3.0.2 - unist-util-is: 6.0.0 - unist-util-visit-parents: 6.0.1 - dev: true - /universalify@0.1.2: resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==} engines: {node: '>= 4.0.0'} @@ -16389,45 +16175,6 @@ 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'} @@ -16605,13 +16352,6 @@ packages: extsprintf: 1.3.0 dev: true - /vfile-location@5.0.2: - resolution: {integrity: sha512-NXPYyxyBSH7zB5U6+3uDdd6Nybz6o6/od9rk8bp9H8GR3L+cm/fC0uUTbqBmUTnMCUDslAGBOIKNfvvb+gGlDg==} - dependencies: - '@types/unist': 3.0.2 - vfile: 6.0.1 - dev: true - /vfile-message@3.1.4: resolution: {integrity: sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==} dependencies: @@ -16619,13 +16359,6 @@ packages: unist-util-stringify-position: 3.0.3 dev: true - /vfile-message@4.0.2: - resolution: {integrity: sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==} - dependencies: - '@types/unist': 3.0.2 - unist-util-stringify-position: 4.0.0 - dev: true - /vfile@5.3.7: resolution: {integrity: sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==} dependencies: @@ -16635,14 +16368,6 @@ packages: vfile-message: 3.1.4 dev: true - /vfile@6.0.1: - resolution: {integrity: sha512-1bYqc7pt6NIADBJ98UiG0Bn/CHIVOoZ/IyEkqIruLg0mE1BKzkOXY2D6CSqQIcKqgadppE5lrxgWXJmXd7zZJw==} - dependencies: - '@types/unist': 3.0.2 - unist-util-stringify-position: 4.0.0 - vfile-message: 4.0.2 - dev: true - /vite-node@0.34.0(@types/node@18.17.5): resolution: {integrity: sha512-rGZMvpb052rjUwJA/a17xMfOibzNF7byMdRSTcN2Lw8uxX08s5EfjWW5mBkm3MSFTPctMSVtT2yC+8ShrZbT5g==} engines: {node: '>=v14.18.0'} @@ -16679,24 +16404,6 @@ 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'} @@ -16787,8 +16494,8 @@ packages: fsevents: 2.3.3 dev: true - /vite@5.0.2(@types/node@18.17.5): - resolution: {integrity: sha512-6CCq1CAJCNM1ya2ZZA7+jS2KgnhbzvxakmlIjN24cF/PXhRMzpM/z8QgsVJA/Dm5fWUWnVEsmtBoMhmerPxT0g==} + /vite@5.0.11(@types/node@18.17.5): + resolution: {integrity: sha512-XBMnDjZcNAw/G1gEiskiM1v6yzM4GE5aMGvhWTlHAYYhxb7S3/V1s3m2LDHa8Vh6yIWYYB0iJwsEaS523c4oYA==} engines: {node: ^18.0.0 || >=20.0.0} hasBin: true peerDependencies: @@ -16817,7 +16524,7 @@ packages: dependencies: '@types/node': 18.17.5 esbuild: 0.19.6 - postcss: 8.4.31 + postcss: 8.4.33 rollup: 4.5.0 optionalDependencies: fsevents: 2.3.3 @@ -16871,12 +16578,12 @@ packages: - terser dev: true - /vitepress@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): - resolution: {integrity: sha512-ikH9pIjOOAbyoYAGBVfTz8TzuXp+UoWaIRMU4bw/oiTg8R65SbAaGKY84xx6TuL+f4VqUJ8lhzW82YyxSLvstA==} + /vitepress@1.0.0-rc.39(@algolia/client-search@4.19.1)(@types/node@18.17.5)(postcss@8.4.31)(search-insights@2.7.0)(typescript@5.1.6): + resolution: {integrity: sha512-EcgoRlAAp37WOxUOYv45oxyhLrcy3Upey+mKpqW3ldsg6Ol4trPndRBk2GO0QiSvEKlb9BMerk49D/bFICN6kg==} hasBin: true peerDependencies: markdown-it-mathjax3: ^4.3.2 - postcss: ^8.4.31 + postcss: ^8.4.33 peerDependenciesMeta: markdown-it-mathjax3: optional: true @@ -16886,19 +16593,19 @@ packages: '@docsearch/css': 3.5.2 '@docsearch/js': 3.5.2(@algolia/client-search@4.19.1)(search-insights@2.7.0) '@types/markdown-it': 13.0.7 - '@vitejs/plugin-vue': 4.5.0(vite@5.0.2)(vue@3.3.8) + '@vitejs/plugin-vue': 5.0.3(vite@5.0.11)(vue@3.4.15) '@vue/devtools-api': 6.5.1 - '@vueuse/core': 10.6.1(vue@3.3.8) - '@vueuse/integrations': 10.6.1(focus-trap@7.5.4)(vue@3.3.8) + '@vueuse/core': 10.7.2(vue@3.4.15) + '@vueuse/integrations': 10.7.2(focus-trap@7.5.4)(vue@3.4.15) focus-trap: 7.5.4 mark.js: 8.11.1 minisearch: 6.3.0 - mrmime: 1.0.1 postcss: 8.4.31 - shikiji: 0.7.4 - shikiji-transformers: 0.7.4 - vite: 5.0.2(@types/node@18.17.5) - vue: 3.3.8(typescript@5.1.6) + shikiji: 0.9.19 + shikiji-core: 0.9.19 + shikiji-transformers: 0.9.19 + vite: 5.0.11(@types/node@18.17.5) + vue: 3.4.15(typescript@5.1.6) transitivePeerDependencies: - '@algolia/client-search' - '@types/node' @@ -17057,7 +16764,7 @@ packages: dependencies: vue: 3.3.4 - /vue-demi@0.14.6(vue@3.3.8): + /vue-demi@0.14.6(vue@3.4.15): resolution: {integrity: sha512-8QA7wrYSHKaYgUxDA5ZC24w+eHm3sYCbp0EzcDwKqN3p6HqtTCGR/GVsPyZW92unff4UlcSh++lmqDWN3ZIq4w==} engines: {node: '>=12'} hasBin: true @@ -17069,7 +16776,7 @@ packages: '@vue/composition-api': optional: true dependencies: - vue: 3.3.8(typescript@5.1.6) + vue: 3.4.15(typescript@5.1.6) dev: true /vue@3.3.4: @@ -17097,19 +16804,19 @@ packages: typescript: 5.0.4 dev: true - /vue@3.3.8(typescript@5.1.6): - resolution: {integrity: sha512-5VSX/3DabBikOXMsxzlW8JyfeLKlG9mzqnWgLQLty88vdZL7ZJgrdgBOmrArwxiLtmS+lNNpPcBYqrhE6TQW5w==} + /vue@3.4.15(typescript@5.1.6): + resolution: {integrity: sha512-jC0GH4KkWLWJOEQjOpkqU1bQsBwf4R1rsFtw5GQJbjHVKWDzO6P0nWWBTmjp1xSemAioDFj1jdaK1qa3DnMQoQ==} peerDependencies: typescript: '*' peerDependenciesMeta: typescript: optional: true dependencies: - '@vue/compiler-dom': 3.3.8 - '@vue/compiler-sfc': 3.3.8 - '@vue/runtime-dom': 3.3.8 - '@vue/server-renderer': 3.3.8(vue@3.3.8) - '@vue/shared': 3.3.8 + '@vue/compiler-dom': 3.4.15 + '@vue/compiler-sfc': 3.4.15 + '@vue/runtime-dom': 3.4.15 + '@vue/server-renderer': 3.4.15(vue@3.4.15) + '@vue/shared': 3.4.15 typescript: 5.1.6 dev: true @@ -17177,10 +16884,6 @@ packages: minimalistic-assert: 1.0.1 dev: true - /web-namespaces@2.0.1: - resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==} - dev: true - /web-streams-polyfill@3.2.1: resolution: {integrity: sha512-e0MO3wdXWKrLbL0DgGnUV7WHVuw9OUvL4hjgnPkIeEvESk74gAITi5G606JtZPp39cd8HA9VQzCIvA49LpPN5Q==} engines: {node: '>= 8'} From d2c82c18022957f8743d656b0e6017be05ba0b53 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 19 Jan 2024 12:06:53 +0530 Subject: [PATCH 45/50] Use cache to store snapshots --- .github/workflows/e2e.yml | 49 +++++++++++++++++++ cSpell.json | 1 + cypress.config.cjs | 11 ++++- .../integration/other/configuration.spec.js | 1 - cypress/integration/other/rerender.spec.js | 2 - cypress/integration/rendering/gantt.spec.js | 13 +++-- cypress/support/commands.js | 12 +++-- 7 files changed, 77 insertions(+), 12 deletions(-) diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index 71806a9c4..09e8546ff 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -9,8 +9,44 @@ permissions: contents: read jobs: + cache: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v2 + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 18.x + + - name: Cache snapshots + id: cache-snapshot + uses: actions/cache@v4 + with: + save-always: true + path: ./cypress/snapshots + key: ${{ runner.os }}-snapshots + + - name: Switch to base branch + if: ${{ steps.cache-snapshot.outputs.cache-hit != 'true' }} + uses: actions/checkout@v4 + with: + ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event_name == 'merge_group' && github.event.merge_group.base.sha || 'develop' }} + + - name: Cypress run + uses: cypress-io/github-action@v4 + id: cypress-snapshot-gen + if: ${{ steps.cache-snapshot.outputs.cache-hit != 'true' }} + with: + start: pnpm run dev + wait-on: 'http://localhost:9000' + browser: chrome + spec: | + cypress/integration/rendering/flowchart-v2.spec.js + e2e: runs-on: ubuntu-latest + needs: cache strategy: fail-fast: false matrix: @@ -27,6 +63,13 @@ jobs: with: node-version: ${{ matrix.node-version }} + - name: Cache snapshots + id: cache-snapshot + uses: actions/cache/restore@v3 + with: + path: ./cypress/snapshots + key: ${{ runner.os }}-snapshots + # Install NPM dependencies, cache them correctly # and run all Cypress tests - name: Cypress run @@ -38,14 +81,19 @@ jobs: with: start: pnpm run dev:coverage wait-on: 'http://localhost:9000' + browser: chrome # Disable recording if we don't have an API key # e.g. if this action was run from a fork record: ${{ secrets.CYPRESS_RECORD_KEY != '' }} parallel: ${{ secrets.CYPRESS_RECORD_KEY != '' }} + # TODO: Remove + spec: | + cypress/integration/rendering/flowchart-v2.spec.js env: CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }} VITEST_COVERAGE: true CYPRESS_COMMIT: ${{ github.sha }} + - name: Upload Coverage to Codecov uses: codecov/codecov-action@v3 # Run step only pushes to develop and pull_requests @@ -57,6 +105,7 @@ jobs: fail_ci_if_error: false verbose: true token: 6845cc80-77ee-4e17-85a1-026cd95e0766 + - name: Upload Artifacts uses: actions/upload-artifact@v3 if: ${{ failure() && steps.cypress.conclusion == 'failure' }} diff --git a/cSpell.json b/cSpell.json index 3ea9594f7..82c1c81c4 100644 --- a/cSpell.json +++ b/cSpell.json @@ -124,6 +124,7 @@ "sidharth", "sidharthv", "sphinxcontrib", + "ssim", "startx", "starty", "statediagram", diff --git a/cypress.config.cjs b/cypress.config.cjs index 30076c56e..c754b465f 100644 --- a/cypress.config.cjs +++ b/cypress.config.cjs @@ -4,12 +4,21 @@ const { defineConfig } = require('cypress'); const { addMatchImageSnapshotPlugin } = require('cypress-image-snapshot/plugin'); const coverage = require('@cypress/code-coverage/task'); + module.exports = defineConfig({ projectId: 'n2sma2', + viewportWidth: 1440, + viewportHeight: 1024, e2e: { - specPattern: 'cypress/integration/**/*.{js,jsx,ts,tsx}', + specPattern: 'cypress/integration/**/*.{js,ts}', setupNodeEvents(on, config) { coverage(on, config); + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.name === 'chrome' && browser.isHeadless) { + launchOptions.args.push('--window-size=1440,1024', '--force-device-scale-factor=1'); + } + return launchOptions; + }); addMatchImageSnapshotPlugin(on, config); // copy any needed variables from process.env to config.env config.env.useAppli = process.env.USE_APPLI ? true : false; diff --git a/cypress/integration/other/configuration.spec.js b/cypress/integration/other/configuration.spec.js index 7cbc5d105..23338271f 100644 --- a/cypress/integration/other/configuration.spec.js +++ b/cypress/integration/other/configuration.spec.js @@ -117,7 +117,6 @@ describe('Configuration', () => { }); it('should not taint the initial configuration when using multiple directives', () => { const url = 'http://localhost:9000/regression/issue-1874.html'; - cy.viewport(1440, 1024); cy.visit(url); cy.get('svg'); diff --git a/cypress/integration/other/rerender.spec.js b/cypress/integration/other/rerender.spec.js index f160a2e27..d14c6257e 100644 --- a/cypress/integration/other/rerender.spec.js +++ b/cypress/integration/other/rerender.spec.js @@ -1,14 +1,12 @@ describe('Rerendering', () => { it('should be able to render after an error has occurred', () => { const url = 'http://localhost:9000/render-after-error.html'; - cy.viewport(1440, 1024); cy.visit(url); cy.get('#graphDiv').should('exist'); }); it('should be able to render and rerender a graph via API', () => { const url = 'http://localhost:9000/rerender.html'; - cy.viewport(1440, 1024); cy.visit(url); cy.get('#graph [id^=flowchart-A]').should('have.text', 'XMas'); diff --git a/cypress/integration/rendering/gantt.spec.js b/cypress/integration/rendering/gantt.spec.js index 998a092c2..73ff4ee00 100644 --- a/cypress/integration/rendering/gantt.spec.js +++ b/cypress/integration/rendering/gantt.spec.js @@ -245,7 +245,10 @@ describe('Gantt diagram', () => { const style = svg.attr('style'); expect(style).to.match(/^max-width: [\d.]+px;$/); const maxWidthValue = parseFloat(style.match(/[\d.]+/g).join('')); - expect(maxWidthValue).to.be.within(984 * 0.95, 984 * 1.05); + expect(maxWidthValue).to.be.within( + Cypress.config().viewportWidth * 0.95, + Cypress.config().viewportWidth * 1.05 + ); }); }); @@ -285,11 +288,11 @@ describe('Gantt diagram', () => { { gantt: { useMaxWidth: false } } ); cy.get('svg').should((svg) => { - // const height = parseFloat(svg.attr('height')); const width = parseFloat(svg.attr('width')); - // use within because the absolute value can be slightly different depending on the environment ±5% - // expect(height).to.be.within(484 * 0.95, 484 * 1.05); - expect(width).to.be.within(984 * 0.95, 984 * 1.05); + expect(width).to.be.within( + Cypress.config().viewportWidth * 0.95, + Cypress.config().viewportWidth * 1.05 + ); expect(svg).to.not.have.attr('style'); }); }); diff --git a/cypress/support/commands.js b/cypress/support/commands.js index 3589640d9..7a77b3ba6 100644 --- a/cypress/support/commands.js +++ b/cypress/support/commands.js @@ -24,8 +24,14 @@ // -- This is will overwrite an existing command -- // Cypress.Commands.overwrite("visit", (originalFn, url, options) => { ... }) -// import '@percy/cypress'; - import { addMatchImageSnapshotCommand } from 'cypress-image-snapshot/command'; -addMatchImageSnapshotCommand(); +addMatchImageSnapshotCommand({ + comparisonMethod: 'ssim', + failureThreshold: 0.01, + failureThresholdType: 'percent', + customDiffConfig: { + ssim: 'fast', + }, + blur: 1, +}); From 76dacf8e90388042cf6171b5aa5aac704d34c7e3 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 19 Jan 2024 12:10:39 +0530 Subject: [PATCH 46/50] E2E test --- cypress/integration/rendering/flowchart-v2.spec.js | 1 - 1 file changed, 1 deletion(-) diff --git a/cypress/integration/rendering/flowchart-v2.spec.js b/cypress/integration/rendering/flowchart-v2.spec.js index e23820ffa..fa625159d 100644 --- a/cypress/integration/rendering/flowchart-v2.spec.js +++ b/cypress/integration/rendering/flowchart-v2.spec.js @@ -6,7 +6,6 @@ describe('Flowchart v2', () => { `flowchart TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} - C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[fa:fa-car Car] `, From 7805e054957b019efa138ba2bece6889ac62ecf3 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 19 Jan 2024 12:15:01 +0530 Subject: [PATCH 47/50] Update lockfile --- pnpm-lock.yaml | 121 ++++++++----------------------------------------- 1 file changed, 19 insertions(+), 102 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b9c49e0a0..2484f6312 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -377,7 +377,7 @@ importers: version: 1.0.0-alpha.72(@algolia/client-search@4.19.1)(@types/node@18.17.5)(search-insights@2.7.0) vitepress-plugin-search: specifier: ^1.0.4-alpha.20 - version: 1.0.4-alpha.20(flexsearch@0.7.31)(vitepress@1.0.0-alpha.72)(vue@3.3.8) + version: 1.0.4-alpha.20(flexsearch@0.7.31)(vitepress@1.0.0-alpha.72)(vue@3.4.15) packages/mermaid-example-diagram: dependencies: @@ -464,7 +464,7 @@ importers: version: 1.1.0 unocss: specifier: ^0.58.0 - version: 0.58.0(postcss@8.4.31)(rollup@2.79.1)(vite@4.5.0) + version: 0.58.0(postcss@8.4.33)(rollup@2.79.1)(vite@4.5.0) unplugin-vue-components: specifier: ^0.26.0 version: 0.26.0(rollup@2.79.1)(vue@3.3.4) @@ -476,7 +476,7 @@ importers: version: 0.17.0(vite@4.5.0)(workbox-build@7.0.0)(workbox-window@7.0.0) vitepress: specifier: 1.0.0-rc.39 - version: 1.0.0-rc.39(@algolia/client-search@4.19.1)(@types/node@18.17.5)(postcss@8.4.31)(search-insights@2.7.0)(typescript@5.1.6) + version: 1.0.0-rc.39(@algolia/client-search@4.19.1)(@types/node@18.17.5)(postcss@8.4.33)(search-insights@2.7.0)(typescript@5.1.6) workbox-window: specifier: ^7.0.0 version: 7.0.0 @@ -5593,7 +5593,7 @@ packages: sirv: 2.0.3 dev: true - /@unocss/postcss@0.58.0(postcss@8.4.31): + /@unocss/postcss@0.58.0(postcss@8.4.33): resolution: {integrity: sha512-2hAwLbfUFqysi8FN1cn3xkHy5GhLMlYy6W4NrAZ2ws7F2MKpsCT2xCj7dT5cI2tW8ulD2YoVbKH15dBhNsMNUA==} engines: {node: '>=14'} peerDependencies: @@ -5605,7 +5605,7 @@ packages: css-tree: 2.3.1 fast-glob: 3.3.2 magic-string: 0.30.5 - postcss: 8.4.31 + postcss: 8.4.33 dev: true /@unocss/preset-attributify@0.58.0: @@ -5876,15 +5876,6 @@ packages: estree-walker: 2.0.2 source-map-js: 1.0.2 - /@vue/compiler-core@3.3.8: - resolution: {integrity: sha512-hN/NNBUECw8SusQvDSqqcVv6gWq8L6iAktUR0UF3vGu2OhzRqcOiAno0FmBJWwxhYEXRlQJT5XnoKsVq1WZx4g==} - dependencies: - '@babel/parser': 7.23.5 - '@vue/shared': 3.3.8 - estree-walker: 2.0.2 - source-map-js: 1.0.2 - dev: true - /@vue/compiler-core@3.4.15: resolution: {integrity: sha512-XcJQVOaxTKCnth1vCxEChteGuwG6wqnUHxAm1DO3gCz0+uXKaJNx8/digSz4dLALCy8n2lKq24jSUs8segoqIw==} dependencies: @@ -5901,13 +5892,6 @@ packages: '@vue/compiler-core': 3.3.4 '@vue/shared': 3.3.4 - /@vue/compiler-dom@3.3.8: - resolution: {integrity: sha512-+PPtv+p/nWDd0AvJu3w8HS0RIm/C6VGBIRe24b9hSyNWOAPEUosFZ5diwawwP8ip5sJ8n0Pe87TNNNHnvjs0FQ==} - dependencies: - '@vue/compiler-core': 3.3.8 - '@vue/shared': 3.3.8 - dev: true - /@vue/compiler-dom@3.4.15: resolution: {integrity: sha512-wox0aasVV74zoXyblarOM3AZQz/Z+OunYcIHe1OsGclCHt8RsRm04DObjefaI82u6XDzv+qGWZ24tIsRAIi5MQ==} dependencies: @@ -5929,21 +5913,6 @@ packages: postcss: 8.4.31 source-map-js: 1.0.2 - /@vue/compiler-sfc@3.3.8: - resolution: {integrity: sha512-WMzbUrlTjfYF8joyT84HfwwXo+8WPALuPxhy+BZ6R4Aafls+jDBnSz8PDz60uFhuqFbl3HxRfxvDzrUf3THwpA==} - dependencies: - '@babel/parser': 7.23.5 - '@vue/compiler-core': 3.3.8 - '@vue/compiler-dom': 3.3.8 - '@vue/compiler-ssr': 3.3.8 - '@vue/reactivity-transform': 3.3.8 - '@vue/shared': 3.3.8 - estree-walker: 2.0.2 - magic-string: 0.30.5 - postcss: 8.4.31 - source-map-js: 1.0.2 - dev: true - /@vue/compiler-sfc@3.4.15: resolution: {integrity: sha512-LCn5M6QpkpFsh3GQvs2mJUOAlBQcCco8D60Bcqmf3O3w5a+KWS5GvYbrrJBkgvL1BDnTp+e8q0lXCLgHhKguBA==} dependencies: @@ -5964,13 +5933,6 @@ packages: '@vue/compiler-dom': 3.3.4 '@vue/shared': 3.3.4 - /@vue/compiler-ssr@3.3.8: - resolution: {integrity: sha512-hXCqQL/15kMVDBuoBYpUnSYT8doDNwsjvm3jTefnXr+ytn294ySnT8NlsFHmTgKNjwpuFy7XVV8yTeLtNl/P6w==} - dependencies: - '@vue/compiler-dom': 3.3.8 - '@vue/shared': 3.3.8 - dev: true - /@vue/compiler-ssr@3.4.15: resolution: {integrity: sha512-1jdeQyiGznr8gjFDadVmOJqZiLNSsMa5ZgqavkPZ8O2wjHv0tVuAEsw5hTdUoUW4232vpBbL/wJhzVW/JwY1Uw==} dependencies: @@ -5994,27 +5956,11 @@ packages: estree-walker: 2.0.2 magic-string: 0.30.5 - /@vue/reactivity-transform@3.3.8: - resolution: {integrity: sha512-49CvBzmZNtcHua0XJ7GdGifM8GOXoUMOX4dD40Y5DxI3R8OUhMlvf2nvgUAcPxaXiV5MQQ1Nwy09ADpnLQUqRw==} - dependencies: - '@babel/parser': 7.23.5 - '@vue/compiler-core': 3.3.8 - '@vue/shared': 3.3.8 - estree-walker: 2.0.2 - magic-string: 0.30.5 - dev: true - /@vue/reactivity@3.3.4: resolution: {integrity: sha512-kLTDLwd0B1jG08NBF3R5rqULtv/f8x3rOFByTDz4J53ttIQEDmALqKqXY0J+XQeN0aV2FBxY8nJDf88yvOPAqQ==} dependencies: '@vue/shared': 3.3.4 - /@vue/reactivity@3.3.8: - resolution: {integrity: sha512-ctLWitmFBu6mtddPyOKpHg8+5ahouoTCRtmAHZAXmolDtuZXfjL2T3OJ6DL6ezBPQB1SmMnpzjiWjCiMYmpIuw==} - dependencies: - '@vue/shared': 3.3.8 - dev: true - /@vue/reactivity@3.4.15: resolution: {integrity: sha512-55yJh2bsff20K5O84MxSvXKPHHt17I2EomHznvFiJCAZpJTNW8IuLj1xZWMLELRhBK3kkFV/1ErZGHJfah7i7w==} dependencies: @@ -6027,13 +5973,6 @@ packages: '@vue/reactivity': 3.3.4 '@vue/shared': 3.3.4 - /@vue/runtime-core@3.3.8: - resolution: {integrity: sha512-qurzOlb6q26KWQ/8IShHkMDOuJkQnQcTIp1sdP4I9MbCf9FJeGVRXJFr2mF+6bXh/3Zjr9TDgURXrsCr9bfjUw==} - dependencies: - '@vue/reactivity': 3.3.8 - '@vue/shared': 3.3.8 - dev: true - /@vue/runtime-core@3.4.15: resolution: {integrity: sha512-6E3by5m6v1AkW0McCeAyhHTw+3y17YCOKG0U0HDKDscV4Hs0kgNT5G+GCHak16jKgcCDHpI9xe5NKb8sdLCLdw==} dependencies: @@ -6048,14 +5987,6 @@ packages: '@vue/shared': 3.3.4 csstype: 3.1.2 - /@vue/runtime-dom@3.3.8: - resolution: {integrity: sha512-Noy5yM5UIf9UeFoowBVgghyGGPIDPy1Qlqt0yVsUdAVbqI8eeMSsTqBtauaEoT2UFXUk5S64aWVNJN4MJ2vRdA==} - dependencies: - '@vue/runtime-core': 3.3.8 - '@vue/shared': 3.3.8 - csstype: 3.1.2 - dev: true - /@vue/runtime-dom@3.4.15: resolution: {integrity: sha512-EVW8D6vfFVq3V/yDKNPBFkZKGMFSvZrUQmx196o/v2tHKdwWdiZjYUBS+0Ez3+ohRyF8Njwy/6FH5gYJ75liUw==} dependencies: @@ -6073,16 +6004,6 @@ packages: '@vue/shared': 3.3.4 vue: 3.3.4 - /@vue/server-renderer@3.3.8(vue@3.3.8): - resolution: {integrity: sha512-zVCUw7RFskvPuNlPn/8xISbrf0zTWsTSdYTsUTN1ERGGZGVnRxM2QZ3x1OR32+vwkkCm0IW6HmJ49IsPm7ilLg==} - peerDependencies: - vue: 3.3.8 - dependencies: - '@vue/compiler-ssr': 3.3.8 - '@vue/shared': 3.3.8 - vue: 3.3.8(typescript@5.0.4) - dev: true - /@vue/server-renderer@3.4.15(vue@3.4.15): resolution: {integrity: sha512-3HYzaidu9cHjrT+qGUuDhFYvF/j643bHC6uUN9BgM11DVy+pM6ATsG6uPBLnkwOgs7BpJABReLmpL3ZPAsUaqw==} peerDependencies: @@ -6090,16 +6011,12 @@ packages: dependencies: '@vue/compiler-ssr': 3.4.15 '@vue/shared': 3.4.15 - vue: 3.4.15(typescript@5.1.6) + vue: 3.4.15(typescript@5.0.4) dev: true /@vue/shared@3.3.4: resolution: {integrity: sha512-7OjdcV8vQ74eiz1TZLzZP4JwqM5fA94K6yntPS5Z25r9HDuGNzaGdgvwKYq6S+MxwF0TFRwe50fIR/MYnakdkQ==} - /@vue/shared@3.3.8: - resolution: {integrity: sha512-8PGwybFwM4x8pcfgqEQFy70NaQxASvOC5DJwLQfpArw1UDfUXrJkdxD3BhVTMS+0Lef/TU7YO0Jvr0jJY8T+mw==} - dev: true - /@vue/shared@3.4.15: resolution: {integrity: sha512-KzfPTxVaWfB+eGcGdbSf4CWdaXcGDqckoeXUh7SB3fZdEtzPCK2Vq9B/lRRL3yutax/LWITz+SwvgyOxz5V75g==} dev: true @@ -16175,7 +16092,7 @@ packages: engines: {node: '>= 10.0.0'} dev: true - /unocss@0.58.0(postcss@8.4.31)(rollup@2.79.1)(vite@4.5.0): + /unocss@0.58.0(postcss@8.4.33)(rollup@2.79.1)(vite@4.5.0): resolution: {integrity: sha512-MSPRHxBqWN+1AHGV+J5uUy4//e6ZBK6O+ISzD0qrXcCD/GNtxk1+lYjOK2ltkUiKX539+/KF91vNxzhhwEf+xA==} engines: {node: '>=14'} peerDependencies: @@ -16191,7 +16108,7 @@ packages: '@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/postcss': 0.58.0(postcss@8.4.33) '@unocss/preset-attributify': 0.58.0 '@unocss/preset-icons': 0.58.0 '@unocss/preset-mini': 0.58.0 @@ -16530,7 +16447,7 @@ packages: fsevents: 2.3.3 dev: true - /vitepress-plugin-search@1.0.4-alpha.20(flexsearch@0.7.31)(vitepress@1.0.0-alpha.72)(vue@3.3.8): + /vitepress-plugin-search@1.0.4-alpha.20(flexsearch@0.7.31)(vitepress@1.0.0-alpha.72)(vue@3.4.15): resolution: {integrity: sha512-zG+ev9pw1Mg7htABlFCNXb8XwnKN+qfTKw+vU0Ers6RIrABx+45EAAFBoaL1mEpl1FRFn1o/dQ7F4b8GP6HdGQ==} engines: {node: ^14.13.1 || ^16.7.0 || >=18} peerDependencies: @@ -16544,7 +16461,7 @@ packages: glob-to-regexp: 0.4.1 markdown-it: 13.0.1 vitepress: 1.0.0-alpha.72(@algolia/client-search@4.19.1)(@types/node@18.17.5)(search-insights@2.7.0) - vue: 3.3.8(typescript@5.0.4) + vue: 3.4.15(typescript@5.0.4) dev: true /vitepress@1.0.0-alpha.72(@algolia/client-search@4.19.1)(@types/node@18.17.5)(search-insights@2.7.0): @@ -16578,7 +16495,7 @@ packages: - terser dev: true - /vitepress@1.0.0-rc.39(@algolia/client-search@4.19.1)(@types/node@18.17.5)(postcss@8.4.31)(search-insights@2.7.0)(typescript@5.1.6): + /vitepress@1.0.0-rc.39(@algolia/client-search@4.19.1)(@types/node@18.17.5)(postcss@8.4.33)(search-insights@2.7.0)(typescript@5.1.6): resolution: {integrity: sha512-EcgoRlAAp37WOxUOYv45oxyhLrcy3Upey+mKpqW3ldsg6Ol4trPndRBk2GO0QiSvEKlb9BMerk49D/bFICN6kg==} hasBin: true peerDependencies: @@ -16600,7 +16517,7 @@ packages: focus-trap: 7.5.4 mark.js: 8.11.1 minisearch: 6.3.0 - postcss: 8.4.31 + postcss: 8.4.33 shikiji: 0.9.19 shikiji-core: 0.9.19 shikiji-transformers: 0.9.19 @@ -16788,19 +16705,19 @@ packages: '@vue/server-renderer': 3.3.4(vue@3.3.4) '@vue/shared': 3.3.4 - /vue@3.3.8(typescript@5.0.4): - resolution: {integrity: sha512-5VSX/3DabBikOXMsxzlW8JyfeLKlG9mzqnWgLQLty88vdZL7ZJgrdgBOmrArwxiLtmS+lNNpPcBYqrhE6TQW5w==} + /vue@3.4.15(typescript@5.0.4): + resolution: {integrity: sha512-jC0GH4KkWLWJOEQjOpkqU1bQsBwf4R1rsFtw5GQJbjHVKWDzO6P0nWWBTmjp1xSemAioDFj1jdaK1qa3DnMQoQ==} peerDependencies: typescript: '*' peerDependenciesMeta: typescript: optional: true dependencies: - '@vue/compiler-dom': 3.3.8 - '@vue/compiler-sfc': 3.3.8 - '@vue/runtime-dom': 3.3.8 - '@vue/server-renderer': 3.3.8(vue@3.3.8) - '@vue/shared': 3.3.8 + '@vue/compiler-dom': 3.4.15 + '@vue/compiler-sfc': 3.4.15 + '@vue/runtime-dom': 3.4.15 + '@vue/server-renderer': 3.4.15(vue@3.4.15) + '@vue/shared': 3.4.15 typescript: 5.0.4 dev: true From 448756ab54480e5e82b5290c00ec3350c6f34879 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 19 Jan 2024 12:17:20 +0530 Subject: [PATCH 48/50] Fix lint --- .github/workflows/e2e.yml | 4 ++-- cypress.config.cjs | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index 09e8546ff..a357c1c99 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -32,7 +32,7 @@ jobs: uses: actions/checkout@v4 with: ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event_name == 'merge_group' && github.event.merge_group.base.sha || 'develop' }} - + - name: Cypress run uses: cypress-io/github-action@v4 id: cypress-snapshot-gen @@ -43,7 +43,7 @@ jobs: browser: chrome spec: | cypress/integration/rendering/flowchart-v2.spec.js - + e2e: runs-on: ubuntu-latest needs: cache diff --git a/cypress.config.cjs b/cypress.config.cjs index c754b465f..33633920a 100644 --- a/cypress.config.cjs +++ b/cypress.config.cjs @@ -4,7 +4,6 @@ const { defineConfig } = require('cypress'); const { addMatchImageSnapshotPlugin } = require('cypress-image-snapshot/plugin'); const coverage = require('@cypress/code-coverage/task'); - module.exports = defineConfig({ projectId: 'n2sma2', viewportWidth: 1440, From d6e738ac4cf2e208326b0ca3a8702d940cb846ec Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 19 Jan 2024 12:21:51 +0530 Subject: [PATCH 49/50] Run all tests --- .github/workflows/e2e.yml | 5 ----- cypress/integration/rendering/flowchart-v2.spec.js | 1 + 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index a357c1c99..996fc6673 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -41,8 +41,6 @@ jobs: start: pnpm run dev wait-on: 'http://localhost:9000' browser: chrome - spec: | - cypress/integration/rendering/flowchart-v2.spec.js e2e: runs-on: ubuntu-latest @@ -86,9 +84,6 @@ jobs: # e.g. if this action was run from a fork record: ${{ secrets.CYPRESS_RECORD_KEY != '' }} parallel: ${{ secrets.CYPRESS_RECORD_KEY != '' }} - # TODO: Remove - spec: | - cypress/integration/rendering/flowchart-v2.spec.js env: CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }} VITEST_COVERAGE: true diff --git a/cypress/integration/rendering/flowchart-v2.spec.js b/cypress/integration/rendering/flowchart-v2.spec.js index fa625159d..e23820ffa 100644 --- a/cypress/integration/rendering/flowchart-v2.spec.js +++ b/cypress/integration/rendering/flowchart-v2.spec.js @@ -6,6 +6,7 @@ describe('Flowchart v2', () => { `flowchart TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} + C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[fa:fa-car Car] `, From cb0ee5aa419849427b4de5b553ef734d22840cae Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 19 Jan 2024 13:17:14 +0530 Subject: [PATCH 50/50] Use pixelmatch for image comparison --- cSpell.json | 1 + cypress/support/commands.js | 22 +++++++++++++--------- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/cSpell.json b/cSpell.json index 82c1c81c4..4b8772347 100644 --- a/cSpell.json +++ b/cSpell.json @@ -102,6 +102,7 @@ "pathe", "pbrolin", "phpbb", + "pixelmatch", "plantuml", "playfair", "pnpm", diff --git a/cypress/support/commands.js b/cypress/support/commands.js index 7a77b3ba6..6fc1fe17d 100644 --- a/cypress/support/commands.js +++ b/cypress/support/commands.js @@ -26,12 +26,16 @@ import { addMatchImageSnapshotCommand } from 'cypress-image-snapshot/command'; -addMatchImageSnapshotCommand({ - comparisonMethod: 'ssim', - failureThreshold: 0.01, - failureThresholdType: 'percent', - customDiffConfig: { - ssim: 'fast', - }, - blur: 1, -}); +// The SSIM comparison method can be used if the pixelmatch is throwing lots of false positives. +// SSIM actually does not catch minute changes in the image, so it is not as accurate as pixelmatch. +// addMatchImageSnapshotCommand({ +// comparisonMethod: 'ssim', +// failureThreshold: 0.01, +// failureThresholdType: 'percent', +// customDiffConfig: { +// ssim: 'fast', +// }, +// blur: 1, +// }); + +addMatchImageSnapshotCommand();