chore: revise Contributing documentation #3814

weedySeaDragon · 2022-11-18T17:25:40Z

📑 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?

📏 Design Decisions

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

📋 Tasks

Make sure you

📖 have read the contribution guidelines
💻 have added unit/e2e tests (if appropriate)
🔖 targeted develop branch

…psed

weedySeaDragon · 2022-11-18T17:34:53Z

@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.

…er-contributing

sidharthv96

This is really great work!

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

sidharthv96 · 2022-11-18T17:42:46Z

CONTRIBUTING.md

-[Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE)
-
-![A superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif)
+[Please read about how to contribute documentation and code on the Mermaid documentation site.](https://mermaid-js.github.io/mermaid/#/development)


Note that this link will change once this is merged to master.
The current link is to the old version.

sidharthv96 · 2022-11-18T17:48:10Z

packages/mermaid/src/docs/community/development.md


-**Another example:**
+Once development is done we branch a `release` branch from `develop` for testing.


release/vX.X.X branch.

sidharthv96 · 2022-11-18T17:48:41Z

packages/mermaid/src/docs/community/development.md


-`bug/123_nasty_bug_branch`
+Once the release happens we merge the `release` branch with `master` and delete the `release` branch. The live product and on-line documentation are what is in the `master` branch.


We also tag the release. Release branch is not deleted now.

sidharthv96 · 2022-11-18T17:50:39Z

packages/mermaid/src/docs/community/development.md


-The contents of [https://mermaid-js.github.io/mermaid/](https://mermaid-js.github.io/mermaid/) are based on the docs from the `master` branch. Updates committed to the `master` branch are reflected in the [Mermaid Docs](https://mermaid-js.github.io/mermaid/) once released.
+```text
+   [feature | bug | chore | docs]/[issue number]_[short description using dashes ('-') or underscores ('_') instead of spaces]


feature -> feat ?

packages/mermaid/src/docs/community/development.md

sidharthv96 · 2022-11-18T17:57:33Z

packages/mermaid/src/docs/community/development.md

+
+### 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.


Only if it's a minor change(?)

packages/mermaid/src/docs/community/development.md

sidharthv96 · 2022-11-18T17:59:50Z

packages/mermaid/src/docs/community/development.md

-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. Create a Pull Request of your newly forked branch by clicking the green **Create Pull Request** button.
+1.  Login to [GitHub.com](https://www.github.com).
+2.  Navigate to [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs).


Fix path.

We also need to complete #3547 to auto build the docs.

packages/mermaid/src/docs/community/development.md

weedySeaDragon · 2022-11-18T18:48:42Z

@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.)

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>

…' into docs/3682-developer-contributing # Conflicts: # packages/mermaid/src/docs/community/development.md

sidharthv96 · 2022-11-19T17:50:18Z

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 · 2022-11-19T19:40:32Z

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 · 2022-11-21T20:55:47Z

@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 · 2022-11-27T19:41:26Z

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

sidharthv96 · 2022-11-28T07:23:40Z

@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

packages/mermaid/src/docs/community/development.md

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>

sidharthv96 · 2022-11-29T19:22:16Z

@weedySeaDragon you can use the include syntax in docs.
Added support in #3863.

huynhicode · 2022-12-11T23:45:07Z

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 · 2022-12-11T23:46:44Z

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

sidharthv96 · 2023-01-12T15:10:52Z

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

* develop: (815 commits) Move filetype Recommendations to the top Update docs Update integrations.md per review Disable coveralls Update coveralls Ignore bundlephobia Update docs strawman extension and mime type docs Update docs Rename info to note Rename "info" to "note" Update all patch dependencies Fix Directives Documentation Run docs:build Update tutorial link Run build Fix link to Tutorials from n00b-overview page Correct timeline spelling UPdated version to 10.2.3 Remove old changelog ...

* develop: Rerun Support for development in Docker

mermaid-bot · 2023-06-15T06:51:31Z

@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.

[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [mermaid](https://togithub.com/mermaid-js/mermaid) | [`10.2.3` -> `10.2.4`](https://renovatebot.com/diffs/npm/mermaid/10.2.3/10.2.4) | [![age](https://badges.renovateapi.com/packages/npm/mermaid/10.2.4/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/npm/mermaid/10.2.4/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/npm/mermaid/10.2.4/compatibility-slim/10.2.3)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/npm/mermaid/10.2.4/confidence-slim/10.2.3)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>mermaid-js/mermaid (mermaid)</summary> ### [`v10.2.4`](https://togithub.com/mermaid-js/mermaid/releases/tag/v10.2.4): 10.2.4 [Compare Source](https://togithub.com/mermaid-js/mermaid/compare/v10.2.3...v10.2.4) #### Features - Add Plausible analytics to mermaid.js.org by [@sidharthv96](https://togithub.com/sidharthv96) in [mermaid-js/mermaid#4473 - Support for development in Docker by [@nirname](https://togithub.com/nirname) in [mermaid-js/mermaid#4478 - standardize info diagram definitions by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4486 - Change C4 stereotype braces from ASCII <\</>> to Unicode «/» by [@jonathan-r-young](https://togithub.com/jonathan-r-young) in [mermaid-js/mermaid#4460 - Add coverage for E2E tests by [@sidharthv96](https://togithub.com/sidharthv96) in [mermaid-js/mermaid#4498 - set normal mode for vitest coverage by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4505 - Use v8 coverage in vitest by [@sidharthv96](https://togithub.com/sidharthv96) in [mermaid-js/mermaid#4560 - feat(flowchart): add classDef style group definition by [@tomperr](https://togithub.com/tomperr) in [mermaid-js/mermaid#3923 - add cypress coverage clean by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4556 - fix(class): keep members in namespace classes by [@tomperr](https://togithub.com/tomperr) in [mermaid-js/mermaid#4532 #### Bugfixes - Add hint on "flowchart" and "graph" by [@koppor](https://togithub.com/koppor) in [mermaid-js/mermaid#4096 - fix(flowchart): apply style on doublecircle by [@tomperr](https://togithub.com/tomperr) in [mermaid-js/mermaid#4540 - fix not rendered style when style is optional by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4528 - fix(flowchart): allow multiple vertices with style by [@tomperr](https://togithub.com/tomperr) in [mermaid-js/mermaid#4553 #### Documentation - change REAMDME.md coverage from coveralls into codecov by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4507 - Update latest news section by [@huynhicode](https://togithub.com/huynhicode) in [mermaid-js/mermaid#4468 - Fix link to Tutorials from n00b-overview page by [@Spiderpig86](https://togithub.com/Spiderpig86) in [mermaid-js/mermaid#4472 - Fix Directives Documentation by [@adamazing](https://togithub.com/adamazing) in [mermaid-js/mermaid#4475 - Correct "Bronze" spelling in timeline docs by [@adamazing](https://togithub.com/adamazing) in [mermaid-js/mermaid#4467 - Document recommended file extension and MIME type docs by [@bollwyvl](https://togithub.com/bollwyvl) in [mermaid-js/mermaid#4485 - Fix typo in quadrant chart documentation by [@tobie](https://togithub.com/tobie) in [mermaid-js/mermaid#4512 - fix cspell issues in \*.md files by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4531 - docs: Howto on foreground color on timelines by [@mcbeelen](https://togithub.com/mcbeelen) in [mermaid-js/mermaid#4524 - Add citation.cff file by [@schackartk](https://togithub.com/schackartk) in [mermaid-js/mermaid#4521 - Update Tutorials.md by [@ellenealds](https://togithub.com/ellenealds) in [mermaid-js/mermaid#4539 - Add Standard Notes extension in integrations page by [@nienow](https://togithub.com/nienow) in [mermaid-js/mermaid#4557 - Fix up Gantt Chart demo by [@AlexMooney](https://togithub.com/AlexMooney) in [mermaid-js/mermaid#4561 #### Chore - Update all patch dependencies (patch) by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4482 - chore: revise Contributing documentation by [@weedySeaDragon](https://togithub.com/weedySeaDragon) in [mermaid-js/mermaid#3814 - chore(deps): update all minor dependencies (minor) by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4435 - fix(deps): update all patch dependencies (patch) by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4510 - fix(deps): update all patch dependencies (patch) by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4535 - chore(deps): update dependency eslint-plugin-jsdoc to v46 by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4544 - chore(deps): update dependency jsdom to v22 by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4546 - chore(deps): update dependency eslint-plugin-unicorn to v47 by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4545 - chore(deps): update dependency workbox-window to v7 by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4547 - chore(deps): update node.js to v20 by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4548 - fix(deps): update all patch dependencies (patch) by [@renovate](https://togithub.com/renovate) in [mermaid-js/mermaid#4543 - add `Suggested Solutions` field in `bug_report.yml` by [@Yokozuna59](https://togithub.com/Yokozuna59) in [mermaid-js/mermaid#4541 #### New Contributors - [@Spiderpig86](https://togithub.com/Spiderpig86) made their first contribution in [mermaid-js/mermaid#4472 - [@adamazing](https://togithub.com/adamazing) made their first contribution in [mermaid-js/mermaid#4475 - [@koppor](https://togithub.com/koppor) made their first contribution in [mermaid-js/mermaid#4096 - [@nirname](https://togithub.com/nirname) made their first contribution in [mermaid-js/mermaid#4478 - [@Yokozuna59](https://togithub.com/Yokozuna59) made their first contribution in [mermaid-js/mermaid#4486 - [@jonathan-r-young](https://togithub.com/jonathan-r-young) made their first contribution in [mermaid-js/mermaid#4460 - [@tobie](https://togithub.com/tobie) made their first contribution in [mermaid-js/mermaid#4512 - [@schackartk](https://togithub.com/schackartk) made their first contribution in [mermaid-js/mermaid#4521 - [@mcbeelen](https://togithub.com/mcbeelen) made their first contribution in [mermaid-js/mermaid#4524 - [@ellenealds](https://togithub.com/ellenealds) made their first contribution in [mermaid-js/mermaid#4539 - [@nienow](https://togithub.com/nienow) made their first contribution in [mermaid-js/mermaid#4557 - [@AlexMooney](https://togithub.com/AlexMooney) made their first contribution in [mermaid-js/mermaid#4561 **Full Changelog**: mermaid-js/mermaid@v10.2.3...v10.2.4 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/levaintech/contented).  Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

weedySeaDragon added 15 commits November 18, 2022 08:52

reorganize, start adding text

47b695c

added main TOC headings

95120c3

copy working draft to vdocs/community/development.md

135893f

CONTRIBUTING.md is note (with link) to development.md on doc site

dabda9d

add TBD/comments in 'Contribute to Documentation....' section

5eee767

delete vdocs dir; it not longer exists

e022404

clarify section headings; add TODO

16d1610

sidebar: add sub-entries for Development/contribution

548ae5b

add mermaid diagram

535a1fc

Minor wording changes to Tech Reqs/Setup

950832e

nav menu: contributing now points to src/doc about contributing

6b8f60e

sidebar menu: remove sub-sub sections since sub menus cannot be colla…

9c0b81c

…psed

add TODO - PRs should start with... (fix|bug|feat|...)

3bdcfd9

make TODOs bold, ital so they're obv

449cbdf

/doc files changed

acebcbf

weedySeaDragon marked this pull request as draft November 18, 2022 17:30

(minor) fix formatting; add "upvoting" to cSpell.json

a867400

weedySeaDragon marked this pull request as ready for review November 18, 2022 17:40

Merge remote-tracking branch 'MERMAID/develop' into docs/3682-develop…

3fbc26d

…er-contributing

sidharthv96 reviewed Nov 18, 2022

View reviewed changes

weedySeaDragon mentioned this pull request Nov 18, 2022

Readme Updates #3581

Closed

weedySeaDragon and others added 5 commits November 18, 2022 15:24

updates based on sidharthv96's review

bd8f620

questions? search in... capitalize Search, + closed issues

71d2175

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>

spelling: description; .. help us keep release notes organized

0333bc1

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>

update related /docs file

fee63d8

Merge remote-tracking branch 'origin/docs/3682-developer-contributing…

bd5b5cd

…' into docs/3682-developer-contributing # Conflicts: # packages/mermaid/src/docs/community/development.md

weedySeaDragon added 4 commits November 25, 2022 10:37

Merge develop cSpell.json

ee0f872

Merge develop into HEAD; install; lint:fix

3eb2bb9

remove references to old sidebar.md file

b15eacf

(minor) force link check again (too many network calls before)

3c49fb2

fix links

6807f19

sidharthv96 reviewed Nov 28, 2022

View reviewed changes

packages/mermaid/src/docs/community/development.md Outdated Show resolved Hide resolved

sidharthv96 reviewed Nov 28, 2022

View reviewed changes

weedySeaDragon and others added 2 commits November 28, 2022 08:46

simplify pnpm cypress command example

75fa259

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>

fix pnpm dev command example

a497909

sidharthv96 mentioned this pull request Nov 28, 2022

Add support for @include in docs #3863

Merged

3 tasks

huynhicode mentioned this pull request May 2, 2023

Collaborators wanted! #866

Open

sidharthv96 added Contributor needed Area: Documentation labels Jun 15, 2023

sidharthv96 added 7 commits June 15, 2023 09:49

ignore .pnpm-store

5b4efba

Update development.md

ecec4d9

Remove duplication from Contributing.md

186de33

Ignore localhost links

08c1071

Merge branch 'develop' into pr/weedySeaDragon/3814

307aa6f

* develop: Rerun Support for development in Docker

Add docker

66116ef

sidharthv96 merged commit beb3a22 into mermaid-js:develop Jun 15, 2023
13 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: revise Contributing documentation #3814

chore: revise Contributing documentation #3814

weedySeaDragon commented Nov 18, 2022 •

edited

weedySeaDragon commented Nov 18, 2022

sidharthv96 left a comment

sidharthv96 Nov 18, 2022

sidharthv96 Nov 18, 2022

sidharthv96 Nov 18, 2022

sidharthv96 Nov 18, 2022

sidharthv96 Nov 18, 2022

sidharthv96 Nov 18, 2022

weedySeaDragon commented Nov 18, 2022

sidharthv96 commented Nov 19, 2022 •

edited

weedySeaDragon commented Nov 19, 2022 •

edited

weedySeaDragon commented Nov 21, 2022 •

edited

weedySeaDragon commented Nov 27, 2022

sidharthv96 commented Nov 28, 2022

sidharthv96 commented Nov 29, 2022

huynhicode commented Dec 11, 2022 •

edited

huynhicode commented Dec 11, 2022

sidharthv96 commented Jan 12, 2023

mermaid-bot bot commented Jun 15, 2023


		Another example:
		Once development is done we branch a `release` branch from `develop` for testing.


		`bug/123_nasty_bug_branch`
		Once the release happens we merge the `release` branch with `master` and delete the `release` branch. The live product and on-line documentation are what is in the `master` branch.


		### 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.

chore: revise Contributing documentation #3814

chore: revise Contributing documentation #3814

Conversation

weedySeaDragon commented Nov 18, 2022 • edited

📑 Summary

📏 Design Decisions

📋 Tasks

weedySeaDragon commented Nov 18, 2022

sidharthv96 left a comment

Choose a reason for hiding this comment

sidharthv96 Nov 18, 2022

Choose a reason for hiding this comment

sidharthv96 Nov 18, 2022

Choose a reason for hiding this comment

sidharthv96 Nov 18, 2022

Choose a reason for hiding this comment

sidharthv96 Nov 18, 2022

Choose a reason for hiding this comment

sidharthv96 Nov 18, 2022

Choose a reason for hiding this comment

sidharthv96 Nov 18, 2022

Choose a reason for hiding this comment

weedySeaDragon commented Nov 18, 2022

sidharthv96 commented Nov 19, 2022 • edited

weedySeaDragon commented Nov 19, 2022 • edited

weedySeaDragon commented Nov 21, 2022 • edited

weedySeaDragon commented Nov 27, 2022

sidharthv96 commented Nov 28, 2022

sidharthv96 commented Nov 29, 2022

huynhicode commented Dec 11, 2022 • edited

huynhicode commented Dec 11, 2022

sidharthv96 commented Jan 12, 2023

mermaid-bot bot commented Jun 15, 2023

weedySeaDragon commented Nov 18, 2022 •

edited

sidharthv96 commented Nov 19, 2022 •

edited

weedySeaDragon commented Nov 19, 2022 •

edited

weedySeaDragon commented Nov 21, 2022 •

edited

huynhicode commented Dec 11, 2022 •

edited