* develop:
docs: Wrap email in <>
chore(dev-deps): update @typescript-eslint to v6
chore(deps): update all patch dependencies
test(e2e): wait for theme-directives.html
test(e2e): remove unused code in theme-directives
test(e2e): wait for marker_unique_id.html e2e test
Update the `@typescript-eslint/eslint-plugin` and
`@typescript-eslint/parser` plugin to v6.
The full list of changes needed can be found in the
[Announcing typescript-eslint v6 blog post][1], but the ones that
affect us are:
- Dropped support for Node.JS v14.
This isn't a big deal for us, since Mermaid uses a version of
`eslint-plugin-jsdoc` that does not support Node.JS v14 either,
see 120029913d
(chore(deps): update dependency eslint-plugin-jsdoc to v46, 2023-06-27)
- Changes to the `plugin:@typescript-eslint/recommended` configuration.
I've manually changed the following two rules to match their old
`@typescript-eslint/parser` v5 settings, to avoid turning ESLint
warnings into errors:
- `@typescript-eslint/no-explicit-any` to `warn`
- `@typescript-eslint/no-unused-vars` to `warn`
[1]: https://main--typescript-eslint.netlify.app/blog/announcing-typescript-eslint-v6
The `theme-directives.html` test currently sometimes takes a screenshot
before all of the Mermaid diagrams have completed rendering.
We can use the `urlSnapshopTest()` helper function, which waits until
a `.rendered` property exists on the page.
Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>
Sometimes, Cypress takes the screenshot for marker_unique_id.html early,
before mermaid has finished rendering the diagrams.
Fixes: 924c9e913b
Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>
* develop:
chore: Fix type in 'getLineFunctionsWithOffset'
refactor: Add getLineFunctionsWithOffset function
refactor: Move EdgeData to types
fix: PointStart marker refX
chore(deps): update all patch dependencies
refactor: Fix typings in utils.ts
chore: Add @internal to createCSSStyles
chore: Bump version
refactor: Remove unused variables
fix: #4818 support `getClasses` in external diagrams.
* develop: (31 commits)
chore: Update docs
New Mermaid Live Editor for Confluence Cloud (#4814)
Update link to Discourse theme component (#4811)
Update flowchart.md (#4810)
chore: Update docs
"CSS" instead of "css" in flowchart.md (#4797)
Update CONTRIBUTING.md
Update CONTRIBUTING.md
fix: typos (#4801)
chore: Align with convention
add additional test case
chore(deps): update all patch dependencies
chore(deps): update all minor dependencies
added test case
add sanitize text
Update docs
modifications to generic parser
improvements to parseGenericTypes
Update packages/mermaid/src/diagrams/class/svgDraw.js
return comment
...
* develop: (22 commits)
docs: Fix link
Update docs
fix(pie): align slices and legend orders
Mermaid version v10.4.0
unique batches every time, if not repeated tests end up in the same batch
Added missed .md
Increase JS heap
More tests for redirects + prettier
Fixed redirects inside vitepress, extended tests
chore: Explain redirect.ts clearly
Reverted docker compose to develop branch
Run GA
Update docs
Update docs
fix(er): bug if relationship is declared first
update latest news
Removed all n00b file names and added redirects
test(er): add cypress test on entity name alias
feat(er): use square brackets to add aliases
docs(er): add release version for entity name aliases
...
* feature/frontmatterConfig:
Update docs
docs: Add frontmatter config demos
docs: Add frontmatter config docs
fix: XSS vulnerability
chore: Minor typo fixes
chore: Add test with both frontmatter and directive
Update docs
feat: Add support for config in frontmatter
deps: Update unocss and webpack to address vulnerability.
chore: Fix type in assignWithDepth
refactor: Move `sanitizeDirective` into `addDirective`
refactor: Rename and cleanup `directiveSanitizer`
chore(deps): update all patch dependencies
ci(release-drafter): add more release notes categories
Add the following new categories to the release notes:
- **BREAKING CHANGES**
- Performance
- Documentation
I've also made the `feature`, `fix`, and `chore` label point to
their appropriate section.
* master:
Version update and adjusted error diagram
Fix for broker error diagram related #4178
Adding new flowchart tests related to issue #2139
Fix for interim issue with classes in state diagrams
#2139 Applying user defined classes properly when calculating shape width
chore: Ignore localhost
Update packages/mermaid/src/docs/community/development.md
Update docs/community/development.md
docs: Add development example page.
* origin/release/10.3.1: (85 commits)
Version update and adjusted error diagram
Fix for broker error diagram related #4178
Adding new flowchart tests related to issue #2139
Fix for interim issue with classes in state diagrams
use default export in `error` diagram
create `ParserDefinition` type
standardized `error` diagram'
#2139 Applying user defined classes properly when calculating shape width
style: format packages/mermaid/src/config.type.ts
build(types): use prettier conf on config.types.ts
Syntax Update CONTRIBUTING.md
docs: Correct detectType filename
chore: Minor cleanups
chore: remove comment
chore: Remove comments, cleanup
fix!(deps): fix zenuml style leakage. update @zenuml/core to ^3.0.6 to fix the style leakage.
Update selectSvgElement.ts
create `Group` type
Add specialChars in textNoTagsToken, alphaNumToken
Return Unicode Text to idStringToken definition
...
Currently, the `packages/mermaid/src/config.type.ts` types file
(auto-generated via `pnpm run --filter mermaid types:build-config`)
uses the default prettier config.
Instead, we should use the prettier config in the Mermaid repo, as it's
slightly different from the default prettier config.
* develop: (59 commits)
fix!(deps): fix zenuml style leakage. update @zenuml/core to ^3.0.6 to fix the style leakage.
Update selectSvgElement.ts
create `Group` type
Add specialChars in textNoTagsToken, alphaNumToken
Return Unicode Text to idStringToken definition
Add underscore to unit test on special Chars
Revert to old docs concerning quotations marks in string
Refactor unit tests and remove repetition
Correct idStringToken definition to include all individual special tokens
Add unit tests for node ids with special Chars
Create lychee.toml
create `selectSvgElement`
change `svgElem` to `SVG` in `configureSvgSize`
add `configureSvgSize` in infoRenderer
run docs:build
remove info sandbox test case
Remove replaceAll method in addLink
Modify HREF token regex to contain space
Add unit tests for stange node names
Remove escaped quotes with backslash feature
...
This will ensure that alphaNumToken does not lose any of
the previously used tokens in its definition. The same
tokens were added to textNoTagsToken explicitly, because it used to
have alphaNumToken in its definition before I removed it.
Previously, textNoTagsToken and alphaNumToken had many tokens in
common in their definition. To avoid grammar conflicts, the
alphaNumStatement grammar was created. However, I found this
unintuitive and was an extra step just to avoid repetition in
the definitions.
I opted to have repetition in the definitions of textNoTagsToken
and alphaNumToken and it be explicitly clear right away, rather than
have extra grammar statements like alphaNumStatement which don't look
like they do anything at first glance
This attempts to maintain the current behaviour.
Previously, because HREF contained a space and called
a state, the href token was able to be placed in the
beginning of node ids (because it wouldn't conflict
without the space). We require the space to keep that
behaviour.
Originally, I thought this was necessary to prevent parsing
the token as part of an edge. I forgot that the token will always
be separated from the link/edge by the node id. Added an unit test
for an edge case to be certain.
Previously, you were allowed to define a class called 'default'
but were not allowed to use it because the classStatement grammar
expected an alphanum, which did not include the word DEFAULT
Similar to what was done in the class diagram parser,
this will allow string tokens to appear in any state.
This is especially helpful, because it will simplify the
code and any future refactoring
This was never really used and had many things wrong with it.
I believe that if a hex was provided in the diagram specification,
the alphanum grammar would break it up into a BRKT and NUM token
and use the first line with the addVertex() function.
Second, the styleLink grammar provides the exact same functionality
with the linkStyle keyword.
Third, updateLink() expects an array of nums, not a hex digit.
Fourth, no documentation is provided on this grammar statement existing.
Fifth, the unit test does not work in version 10.2.4
What this allows is for idStrings that are separated by
dashes or underscores to be considered one whole string
rather than a bunch of tokens mixed together.
This is necessary for examples such as a-node-graph[text].
Now, the last part of the idString 'graph' will be read as
part of the NODE_STRING token rather than attempting to add
a GRAPH token to the idString.
* develop:
build(docs): handle YAML edgecases in markdown
run pnpm lint:fix
Update cypress/helpers/util.ts
change deprecated `btoa` into `Buffer.from`
allow ts extension imports in cypress ts files
build(docs): allow using custom `editLink`
build(docs): add `editLink: ` to MD frontmatter
build(docs): run remark plugins on MermaidConfig
Fix import file extension
Batch by commit
resolve lint issues for `no-inferrable-types`
fix wrong config paramater in some cypress spec
convert cypress/helpers/util.js into ts
convert file from js into ts
Add a YAML front-matter entry called `editLink` to Markdown files in
Vitepress, e.g.
```markdown
---
editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/src/schemas/config.schema.yaml"
---
Here is my markdown file!
```
Although Vitepress doesn't officially support adding a URL as a
`editLink:` YAML front-matter, we can add a custom `editLink` function
to our Vitepress config that does allow it.
This reverts commit 063cb124cd.
This file was originally added to test whether the new implementation
of the default config in
`packages/mermaid/src/schemas/config.schema.yaml` matched the old
existing default config in `packages/mermaid/src/oldDefaultConfig.ts`,
and this test is no longer needed.
This test was accidentally removed by a bad merge commit, see
29291c89 (Merge branch 'develop' into pr/aloisklink/4112, 2023-07-06).
This test checks whether the default config defined in the
`config.schema.yaml` file matches the old default config defined in
`oldDefaultConfig.ts`.
Fixes: 29291c8901
* develop: (293 commits)
chore: Remove lint warnings in example-diagram
chore: Reduce codecov pushes
Turn off codecov project status check
build(docs): fix links to `config.schema.json`
ci(lint): check if MermaidConfig types are in sync
docs: add link to mermaid config docs in sidebar
test(config): add temp test for defaultConfig
build(types): create types from config JSON Schema
build(types): add script to generate Config types
build(docs): build JSON Schema docs
build: use vite to get default mermaid config
feat: add Mermaid Config in JSON Schema format
docs: add support for ```regexp``` code blocks
test: test partial QuadrantChartConfig options
test: fix types in `config.spec.ts`
style: fix lint issues in src/config.spec.ts
test: rename src/config.spec.js to config.spec.ts
fix(quadrant): make quadrant options optional
fix lint
update homepage community link
...
Fix the link in some Mermaid Config markdown documentation,
which previously pointed to `src/schemas/config.schema.yaml`,
which went nowhere.
Now, these links point to:
- config.schema.json (i.e. the generated JSON file, not YAML)
- links are relative to the markdown documentation
We also needed to store the `schema.json` file in the Vitepress
`public/` folder, as Vitepress otherwise doesn't bundle `.json` files
properly, when running `vitepress build src/vitepress`.
Add a CI check that runs
`pnpm run --filter mermaid types:verify-config` and checks whether
the MermaidConfig TypeScript types are in sync with the MermaidConfig
JSON Schema.
Adds a temporary test to ensure that the new defaultConfig,
generated by Vite automatically from the `MermaidConfig` JSON Schema,
has the same values as the old defaultConfig
(taken from
38013de711/packages/mermaid/src/defaultConfig.ts)
The only minor difference seems to be that:
- `gitGraph` now has a default `useMaxWidth: false` option
(previously used to be `undefined`),
- `class` now has a `htmlLabels` value of `false` instead of `undefined`.
Add script `packages/mermaid/scripts/create-types-from-json-schema.mts`
to automatically generate the TypeScript definition for `MermaidConfig`
from the `MermaidConfig` JSON Schema at
`packages/mermaid/src/schemas/config.schema.yaml`.
To do this, we are using this library
[`json-schema-to-typescript`][1], which is also used by Webpack to
generate their types from their JSON Schema.
In order to make sure that this isn't a breaking change, the script
makes all fields **optional**, as that is what the original typescript
file has.
Additionally, I've put in some custom logic into the script, so that
the exact same order is used for the TypeScript file, to make the
`git diff` easier to review. In the future, we can remove this custom
logic, once we no longer need to worry about `git merge` conflicts.
[1]: https://github.com/bcherny/json-schema-to-typescript
Automatically build documentation for JSON Schema.
This is only built when running with `--vitepress`,
as it currently produces loads of markdown files, which I feel like
we shouldn't be committing.
This currently manually uses some internal `jsonschema2md` functions
so that we can manually control the Markdown output.
Adds a vitepress JsonSchema plugin that automatically loads
the Mermaid Config JSON Schema from a .schema.yaml file and
gets the default values from it.
Add a JSON Schema file (in YAML) for the MermaidConfig.
This JSON Schema file follows [JSON Schema 2019-09][1], with some slight
modifications to work with:
- [json-schema-to-typescript][2]
The `tsType` keyword is used to override the generated TypeScript
type, when it doesn't match the JSON Schema type.
This is used in two cases:
- when the current type cannot be represented in JSON Schema
(e.g. `FontCalculator`, which is a function)
- when the JSON Schema type is narrower than the TypeScript type.
Currently, many enums types are listed as `string` in TypeScript,
but json-schema-to-typescript converts them to `"val1" | "val2"`.
I've manually set them to `string | "val1" | "val2"` to avoid
causing a breaking change in the TypeScript types. We should
remove these in a future major version of TypeScript.
- [@adobe/jsonschema2md][3]
The `meta:enum` keyword is used to add documentation for specific enum
values.
[1]: https://json-schema.org/draft/2019-09/release-notes.html
[2]: https://www.npmjs.com/package/json-schema-to-typescript
[3]: https://www.npmjs.com/package/@adobe/jsonschema2md
Currently, shiki doesn't support code-blocks that use the regexp
language, which means vitepress throws an error on them:
```regexp
^([1-9][0-9]*)(minute|hour|day|week|month)$
```
As a hack until shiki supports them, I've just modified them to get
converted into JavaScript RegEx literal code-blocks, e.g.:
```javascript
/^([1-9][0-9]*)(minute|hour|day|week|month)$/
```
Make the types of the options in QuadrantChartConfig in the
MermaidConfig optional. All of these (except for the values in
`BaseDiagramConfig`) will be automatically set to their
default values, so they're optional from a user perspective.
Replace the TypeScript `enum {a = "a", b = "b"}` types with
TypeScript's literal types (e.g. `"a" | "b"`).
This is because TypeScript enums are
[_not_ a type-level addition to JavaScript][1], and even the official
TypeScript docs say to be careful when using.
[1]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums
Added cypress container (from their official image),
may be reconsidered later to choose our own
The only minor problem is node JS version mistmatch
package.json 18.16.0
docker-compose mermaid 18.16.1
docker-compose cypress 18.16.0
Host option in cypress docker container must be removed
in favor of possible configuration option.
http://localhost:9000 are currently hard-coded, that is bad
Updated ./run script with better documentation
and added some styles too it as well
Started sankey.spec.js as an example
Tooltip is an object that gets reset to an array. It is then looked up for properties without guard, causing array functions like "length" and "constructor" to run into undefined behvaior.
- add types for parameter and returned value and variables
- change the deperated `unescape` into `decodeURIComponent`
- create `CypressConfig` and `CypressMermaidConfig` and `CodeObject` types
- add default value for some parameter
- remove @ts-ignore comments
- rename vitest test and describe title
- remove unnecessary types, e.i, `null` and `number`
- clean `addSVGa11yTitleDescription` and `setA11yDiagramInfo` functions
* develop:
Update docs
Rename info to note
Rename "info" to "note"
Update all patch dependencies
Fix Directives Documentation
Update tutorial link
Run build
Fix link to Tutorials from n00b-overview page
UPdated version to 10.2.3
Remove old changelog
Remove old changelog
Setting version to 10.2.2
#4446 Improved regular expression
#4446 Updating the cleanup criteria
#4438 Reverted to the changes from #4285
Fix download
Fix compile error in docs.
Fix Contributor link in homepage
Update docs
Add hint on "flowchart" and "graph" (and some more styling)
Here are the changes I made:
Removed unnecessary variables and assignments
Removed unnecessary object property assignments
Removed redundant code by consolidating similar conditionals
Removed unused parameters and default values
Simplified some conditionals with boolean expressions
Removed unused variables and imports
Extracted common code into a reusable function
By optimizing the code in these ways, we can reduce the time complexity of the code and improve its performance.
2023-04-24 12:14:40 +05:30
371 changed files with 16861 additions and 9672 deletions
'Prefer using TypeScript union types over TypeScript enum, since TypeScript enums have a bunch of issues, see https://dev.to/dvddpl/whats-the-problem-with-typescript-enums-2okj',
@@ -13,6 +13,6 @@ Describe the way your implementation works or what design decisions you made if
Make sure you
- [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md)
- [ ] :computer: have added unit/e2e tests (if appropriate)
- [ ] :notebook: have added documentation (if appropriate)
- [ ] :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.
Documentation is necessary for all non bugfix/refactoring changes.
Only make changes to files are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs)
Only make changes to files that are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs)
**_DO NOT CHANGE FILES IN `/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)
@@ -20,6 +20,9 @@ Generate diagrams from markdown-like text.
<palign="center">
<ahref="./README.zh-CN.md">简体中文</a>
</p>
<palign="center">
Try Live Editor previews of future releases: <ahref="https://develop.git.mermaid.live/"title="Try the mermaid version from the develop branch.">Develop</a> | <ahref="https://next.git.mermaid.live/"title="Try the mermaid version from the next branch.">Next</a>
</p>
<br>
<br>
@@ -56,11 +59,11 @@ 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/).<br/>
[Tutorials](./docs/config/Tutorials.md) has video tutorials.
Use Mermaid with your favorite applications, check out the list of [Integrations and Usages of Mermaid](./docs/ecosystem/integrations.md).
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.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/community/n00b-overview.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/config/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.
@@ -165,13 +168,7 @@ class Class10 {
int id
size()
}
namespace Namespace01 {
class Class11
class Class12 {
int id
size()
}
}
```
```mermaid
@@ -191,13 +188,7 @@ class Class10 {
int id
size()
}
namespace Namespace01 {
class Class11
class Class12 {
int id
size()
}
}
```
### State diagram [<a href="https://mermaid-js.github.io/mermaid/#/stateDiagram">docs</a> - <a href="https://mermaid.live/edit#pako:eNpdkEFvgzAMhf8K8nEqpYSNthx22Xbcqcexg0sCiZQQlDhIFeK_L8A6TfXp6fOz9ewJGssFVOAJSbwr7ByadGR1n8T6evpO0vQ1uZDSekOrXGFsPqJPO6q-2-imH8f_0TeHXm50lfelsAMjnEHFY6xpMdRAUhhRQxUlFy0GTTXU_RytYeAx-AdXZB1ULWovdoCB7OXWN1CRC-Ju-r3uz6UtchGHJqDbsPygU57iysb2reoWHpyOWBINvsqypb3vFMlw3TfWZF5xiY7keC6zkpUnZIUojwW-FAVvrvn51LLnvOXHQ84Q5nn-AVtLcwk">live editor</a>]
it('New line in node and formatted edge label',()=>{
@@ -736,7 +736,7 @@ flowchart-elk LR
b("\`The dog in **the** hog.(1)
NL\`") --"\`1o **bold**\`"--> c
`,
{titleTopMargin:0}
{flowchart:{titleTopMargin:0}}
);
});
it('Wrapping long text with a new line',()=>{
@@ -749,7 +749,7 @@ Word!
Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. \`) --> c
it('New line in node and formatted edge label',()=>{
@@ -808,7 +808,7 @@ flowchart-elk LR
b("\`The dog in **the** hog.(1)
NL\`") --"\`1o **bold**\`"--> c
`,
{titleTopMargin:0}
{flowchart:{titleTopMargin:0}}
);
});
it('Wrapping long text with a new line',()=>{
@@ -821,7 +821,7 @@ Word!
Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. \`") --> c
it('New line in node and formatted edge label',()=>{
@@ -733,7 +767,7 @@ flowchart LR
b("\`The dog in **the** hog.(1)
NL\`") --"\`1o **bold**\`"--> c
`,
{titleTopMargin:0}
{flowchart:{titleTopMargin:0}}
);
});
it('Wrapping long text with a new line',()=>{
@@ -746,7 +780,7 @@ Word!
Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. \`") --> c
it('New line in node and formatted edge label',()=>{
@@ -805,7 +839,7 @@ flowchart LR
b("\`The dog in **the** hog.(1)
NL\`") --"\`1o **bold**\`"--> c
`,
{titleTopMargin:0}
{flowchart:{titleTopMargin:0}}
);
});
it('Wrapping long text with a new line',()=>{
@@ -818,7 +852,7 @@ Word!
Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. Another line with many, many words. \`") --> c
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/code.md](../../packages/mermaid/src/docs/community/code.md).
# Contributing Code
The basic steps for contributing code are:
```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]
```
```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]
```
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.
## 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]
```
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
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]_**
....
## 3. Update 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<MERMAID_RELEASE_VERSION>+)` in the title or description. It will be replaced automatically with the current version number when the release happens.
eg: `# Feature Name (v<MERMAID_RELEASE_VERSION>+)`
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.**
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
