Contribution documentation improvements

Ronid1 · Dec 11, 2023 · 57f0a3a · 57f0a3a
1 parent 4f9988a
commit 57f0a3a
Show file tree

Hide file tree

Showing 16 changed files with 425 additions and 119 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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,15 +163,13 @@ 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' },
         { text: 'Directives', link: '/config/directives' },
         { 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
@@ -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/.../src/docs/community/docker-development.md → ...ermaid/src/docs/community/docker-setup.md b/.../src/docs/community/docker-development.md → ...ermaid/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
@@ -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
@@ -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/.../mermaid/src/docs/community/newDiagram.md → ...mermaid/src/docs/community/new-diagram.md b/.../mermaid/src/docs/community/newDiagram.md → ...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
@@ -0,0 +1 @@
+quick start contributing guide
diff --git a/...mermaid/src/docs/community/development.md → packages/mermaid/src/docs/community/setup.md b/...mermaid/src/docs/community/development.md → 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)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -46,3 +46,4 @@ stats/

		demos/dev/**
		!/demos/dev/example.html
		tsx-0/**