-
-
Notifications
You must be signed in to change notification settings - Fork 6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore: revise Contributing documentation #3814
Merged
sidharthv96
merged 36 commits into
mermaid-js:develop
from
weedySeaDragon:docs/3682-developer-contributing
Jun 15, 2023
Merged
Changes from 17 commits
Commits
Show all changes
36 commits
Select commit
Hold shift + click to select a range
47b695c
reorganize, start adding text
weedySeaDragon 95120c3
added main TOC headings
weedySeaDragon 135893f
copy working draft to vdocs/community/development.md
weedySeaDragon dabda9d
CONTRIBUTING.md is note (with link) to development.md on doc site
weedySeaDragon 5eee767
add TBD/comments in 'Contribute to Documentation....' section
weedySeaDragon e022404
delete vdocs dir; it not longer exists
weedySeaDragon 16d1610
clarify section headings; add TODO
weedySeaDragon 548ae5b
sidebar: add sub-entries for Development/contribution
weedySeaDragon 535a1fc
add mermaid diagram
weedySeaDragon 950832e
Minor wording changes to Tech Reqs/Setup
weedySeaDragon 6b8f60e
nav menu: contributing now points to src/doc about contributing
weedySeaDragon 9c0b81c
sidebar menu: remove sub-sub sections since sub menus cannot be colla…
weedySeaDragon 3bdcfd9
add TODO - PRs should start with... (fix|bug|feat|...)
weedySeaDragon 449cbdf
make TODOs bold, ital so they're obv
weedySeaDragon acebcbf
/doc files changed
weedySeaDragon a867400
(minor) fix formatting; add "upvoting" to cSpell.json
weedySeaDragon 3fbc26d
Merge remote-tracking branch 'MERMAID/develop' into docs/3682-develop…
weedySeaDragon bd8f620
updates based on sidharthv96's review
weedySeaDragon 71d2175
questions? search in... capitalize Search, + closed issues
weedySeaDragon 0333bc1
spelling: description; .. help us keep release notes organized
weedySeaDragon fee63d8
update related /docs file
weedySeaDragon bd5b5cd
Merge remote-tracking branch 'origin/docs/3682-developer-contributing…
weedySeaDragon ee0f872
Merge develop cSpell.json
weedySeaDragon 3eb2bb9
Merge develop into HEAD; install; lint:fix
weedySeaDragon b15eacf
remove references to old sidebar.md file
weedySeaDragon 3c49fb2
(minor) force link check again (too many network calls before)
weedySeaDragon 6807f19
fix links
weedySeaDragon 75fa259
simplify pnpm cypress command example
weedySeaDragon a497909
fix pnpm dev command example
weedySeaDragon 1a6fd69
Merge branch 'develop' into pr/weedySeaDragon/3814
sidharthv96 5b4efba
ignore .pnpm-store
sidharthv96 ecec4d9
Update development.md
sidharthv96 186de33
Remove duplication from Contributing.md
sidharthv96 08c1071
Ignore localhost links
sidharthv96 307aa6f
Merge branch 'develop' into pr/weedySeaDragon/3814
sidharthv96 66116ef
Add docker
sidharthv96 File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,156 +1,3 @@ | ||
# Contributing | ||
|
||
So you want to help? That's great! | ||
|
||
![Happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) | ||
|
||
Here are a few things to know to get you started on the right path. | ||
|
||
Below link will help you making a copy of the repository in your local system. | ||
|
||
https://docs.github.com/en/get-started/quickstart/fork-a-repo | ||
|
||
## 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 | ||
|
||
```bash | ||
git clone git@github.com:mermaid-js/mermaid.git | ||
cd mermaid | ||
# npx is required for first install as volta support for pnpm is not added yet. | ||
npx pnpm install | ||
pnpm test | ||
``` | ||
|
||
## Committing code | ||
|
||
We make all changes via pull requests. As we have many pull requests from developers new to mermaid, the current approach is to have _knsv, Knut Sveidqvist_ as a main reviewer of changes and merging pull requests. More precisely like this: | ||
|
||
- Large changes reviewed by knsv or other developer asked to review by knsv | ||
- Smaller low-risk changes like dependencies, documentation, etc. can be merged by active collaborators | ||
- Documentation (updates to the `package/mermaid/src/docs` folder is also allowed via direct commits) | ||
|
||
To commit code, create a branch, let it start with the type like feature or bug followed by the issue number for reference and some describing text. | ||
|
||
One example: | ||
|
||
`feature/945_state_diagrams` | ||
|
||
Another: | ||
|
||
`bug/123_nasty_bug_branch` | ||
|
||
## Committing documentation | ||
|
||
Less strict here, it is OK to commit directly in the `develop` branch if you are a collaborator. | ||
|
||
The documentation is written in **Markdown**. 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). | ||
|
||
### Documentation source files are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) | ||
|
||
The source files for the project documentation are located in the [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) directory. This is where you should make changes. | ||
The files under `/packages/mermaid/src/docs` are processed to generate the published documentation, and the resulting files are put into the `/docs` directory. | ||
|
||
```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"] | ||
|
||
``` | ||
|
||
**_DO NOT CHANGE FILES IN `/docs`_** | ||
|
||
### The official documentation site | ||
|
||
**[The mermaid documentation site](https://mermaid-js.github.io/mermaid/) is powered by [Vitepress](https://vitepress.vuejs.org/), a simple documentation site generator.** | ||
|
||
If you want to preview the whole documentation site on your machine: | ||
|
||
```sh | ||
cd packages/mermaid | ||
pnpm i | ||
pnpm docs:dev | ||
``` | ||
|
||
You can now build and serve the documentation site: | ||
|
||
```sh | ||
pnpm docs:serve | ||
``` | ||
|
||
## Branching | ||
|
||
Going forward we will use a git flow inspired approach to branching. So development is done in develop, to do the development in the develop. | ||
|
||
Once development is done we branch a release branch from develop for testing. | ||
|
||
Once the release happens we merge the release branch to master and kill the release branch. | ||
|
||
This means... **branch off your pull request from develop** | ||
|
||
## Content of a pull request | ||
|
||
A new feature has been born. Great! But without the steps below it might just ... fade away ... | ||
|
||
### **Add unit tests for the parsing part** | ||
|
||
This is important so that, if someone else does a change to the grammar that does not know about this great feature, gets notified early on when that change breaks the parser. Another important aspect is that without proper parsing tests refactoring is pretty much impossible. | ||
|
||
### **Add e2e tests** | ||
|
||
This tests the rendering and visual appearance of the diagram. 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, run `pnpm run dev` to start the dev server, after that start cypress by running `pnpm exec cypress open` in the mermaid folder. | ||
|
||
The rendering tests are very straightforward to create. There is a function imgSnapshotTest. This function takes a diagram in text form, the mermaid options and 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 for review it if it differs. | ||
|
||
This is what a rendering test looks like: | ||
|
||
```javascript | ||
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'); | ||
}); | ||
``` | ||
|
||
### **Add documentation for it** | ||
|
||
Finally, if it is not in the documentation, no one will know about it and then **no one will use it**. Wouldn't that be sad? With all the effort that was put into the feature? | ||
|
||
The source files for documentation are in `/packages/mermaid/src/docs` and are written in markdown. Just pick the right section and start typing. See the [Committing Documentation](#committing-documentation) section for more about how the documentation is generated. | ||
|
||
#### Adding to or changing the documentation organization | ||
|
||
If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `mermaid/src/docs/.vitepress/config.js`. | ||
|
||
When changes are committed and then released, they become part of the `master` branch and become part of the published documentation on https://mermaid-js.github.io/mermaid/ | ||
|
||
## 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) | ||
|
||
![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) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -72,6 +72,7 @@ | |
"techn", | ||
"ts-nocheck", | ||
"tuleap", | ||
"upvoting", | ||
"verdana", | ||
"viewports", | ||
"vinod", | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note that this link will change once this is merged to master.
The current link is to the old version.