chore: revise Contributing documentation

[weedySeaDragon]

:bookmark_tabs: Summary

Resolves #3682

Revise the 'Contributing' documentation, including changing CONTRIBUTING.md to just point to docs/community/developer.md

Note: This is still a WIP. I want to get feedback before going any further.

I've made some bold assumptions and statements in here. Do the project maintainers agree?

:straight_ruler: Design Decisions

1. Separate into main sections:
   • Technical Requirements and Setup: the tools that need to be installed, info and/or links for info on installing them, verifying that everything is installed correctly
   • Contributing Code -- This is where I really need feedback.
     • branch naming: I've imposed some standards
     • Write tests: I've going into details about why testing is important, and how specifications and testing are related. Perhaps I've gone into too much detail? (My thought is that with an open source project such as this, many people contributing may not understand the importance of testing and specification. OTOH, we don't want to make it too overwhelming or make the barriers for contributing too high. What's the right balance?
     • Submit Your Pull Request: Would be helpful to have note about being patient and/or other words about how long the process might take.
       • should include a note that you need to update your branch if the underlying develop branch is changed before your PR is merged
   • Contributing Documentation -- This section still needs to be revised.
   • Questions or Suggestions -- This section still needs to be revised. Want to highlight and steer people to the discussions and to search for existing issues/PRs
   • Last words -- This section still needs to be revised.

I find the gifs quite distracting. The Captain America one at the bottom cannot be resized and is too big. If there really needs to be a gif at the bottom, is there a smaller on

:clipboard: Tasks

Make sure you

• [x] :book: have read the contribution guidelines
• [x] :computer: have added unit/e2e tests (if appropriate)
• [x] :bookmark: targeted develop branch

[weedySeaDragon]

@DanielOaks @qurm You both chimed in with #2910 so I'm pinging you to ask for your review. My eyes and brain are saturated and I really need some feedback. :-)

Now that @emersonbottero and @sidharthv96 have done the hard work of converting things to vitepress, I think we should begin to really revise the documentation. This is my first step.

[weedySeaDragon]

@sidharthv96 wrote:

I wonder if we should leave just the bare minimum commands to get it running inside Contributing.md?

I'm conflicted about this because it will mean 2 places that we need to keep that documentation up to date (obv). If there's any way to include the same source in both documentation (.md) files, that'd be super and I'd be all for it.

(Then I'd learn how to do that and we could surely take advantage of using includes in many other places in the documentation.)

[sidharthv96]

Well.......... We are doing pre-processing for docs, so theoretically we could support md file injection 😅, but just because we can doesn't mean we should 😂 How much of an impact would such a feature make?

[weedySeaDragon]

so theoretically we could support md file injection 😅, but just because we can doesn't mean we should 😂 How much of an impact would such a feature make?

Totally agree that just because we can doesn't mean we should :-D

I think it's something to keep in mind. Consider all of the common features of the different diagrams: diagram direction (TB, LR etc) , notes, classDefs, styling, interaction, etc.
So of course all of the documentation for those should be the same.

I suspect (without considering it deeply) that if we can refactor/DRY the parsing, then at that point we should also consider refactoring the documentation (exploring whether we can include .md files).

[weedySeaDragon]

@sidharthv96 FYI: Good news! Vitpress supports .md files included in other .md files!

Vitepress: Markdown File Inclusion

I wondered if they'd have that feature since so many must need it.

Obv it doesn't help with duplicated info in CONTRIBUTING.md since that's not published by vitepress. But for so much other stuff in the documentation, it'll be great.

[weedySeaDragon]

@sidharthv96 - can you look at the link checker? It's failing with "too many network requests".

[sidharthv96]

@weedySeaDragon, they use caching, so the 429 error is fixed after a rerun. But the current error is valid.

✗ [404] https://github.com/mermaid-js/mermaid/tree/develop/src/docs | Failed: Network error: Not Found

[sidharthv96]

@weedySeaDragon you can use the include syntax in docs. Added support in https://github.com/mermaid-js/mermaid/pull/3863.

[huynhicode]

Hello, really great work on this PR!

I was wondering if we may add some explicit instructions on how to contribute to Mermaid so that new contributors can get up and running quickly.

To contribute:

• fork the repo
• clone the repo
• cd into the forked repo
• install Volta
• run volta install node
• run volta install pnpm
• run npx pnpm install

To contribute to the documentation:

• cd into /packages/mermaid/src/docs
• run pnpm docs:dev
• open up localhost:5173/mermaid

To contribute to the core code:

• at the root folder, run pnpm dev
• open up localhost:9000
• make modifications to /packages/mermaid/src/

(e.g. to update the flowchart found at localhost:9000/flowchart.html, go to /packages/mermaid/src/diagrams/flowchart)

To add E2E Tests:

• run pnpm dev
• run pnpm exec cypress open

To submit a Pull Request:

• run pnpm test
• run pnpm lint:fix (if there is a formatting issue)

[huynhicode]

Also, it may be helpful to have instructions on how to get up and running in the Slack workspace as well.

[sidharthv96]

@weedySeaDragon hope you're doing well. There seem to be some TODO: This section is still a WIP. left.

[mermaid-bot[bot]]

@weedySeaDragon, Thank you for the contribution! You are now eligible for a year of Premium account on MermaidChart. Sign up with your GitHub account to activate.