mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-09-14 12:59:46 +02:00
copy working draft to vdocs/community/development.md
This commit is contained in:
Ashley Engelund (weedySeaDragon @ github)
parent
95120c3f21
commit
135893f067
@@ -2,12 +2,12 @@
|
||||
|
||||
## Contents
|
||||
|
||||
[1. Requirements](#requirements)
|
||||
[2. Development Installation](#development-installation)
|
||||
[3. Contributing Code](#contributing-code)
|
||||
[4. Contributing Documentation](#contributing-documentation)
|
||||
[5. Have Questions or Suggestions?](#have-questions-or-suggestions)
|
||||
[6. Last Words](#6-last-words)
|
||||
- [Technical Requirements and Setup](#technical-requirements-and-setup)
|
||||
- [Development Installation](#development-installation)
|
||||
- [Contributing Code](#contributing-code)
|
||||
- [Contributing Documentation](#contributing-documentation)
|
||||
- [Have Questions or Suggestions?](#have-questions-or-suggestions)
|
||||
- [Last Words](#6-last-words)
|
||||
|
||||
---
|
||||
|
||||
@@ -17,41 +17,60 @@ So you want to help? That's great!
|
||||
|
||||
Here are a few things to get you started on the right path.
|
||||
|
||||
## 1. Requirements
|
||||
## Technical Requirements and Setup
|
||||
|
||||
These are the main tools we use for working with the code and information (including documentation):
|
||||
|
||||
- [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`
|
||||
- [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm; needed to install pnpm (see below)
|
||||
|
||||
## 2. Development Installation _(todo - merge this under development? )_
|
||||
### 1. Fork and clone the repository
|
||||
|
||||
In GitHub, you first _fork_ a repository when you are going to make changes and submit pull requests.
|
||||
|
||||
Then you _clone_ a copy to your local development machine (e.g. where you code) to make a copy with all the files to work with.
|
||||
|
||||
In GitHub, you _fork_ a repository when you are going to make changes and submit pull requests.
|
||||
[Here is a GitHub document that gives an overview of the process.](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
|
||||
|
||||
### 2. Install pnpm
|
||||
|
||||
Once you have cloned the repository onto your development machine, change into the `mermaid` folder so that you can install `pnpm`. You will need `npx` to install pnpm because volta doesn't support it yet.
|
||||
|
||||
Ex:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:mermaid-js/mermaid.git
|
||||
# Change into the mermaid directory (the top level director of the mermaid project repository)
|
||||
cd mermaid
|
||||
# npx is required for first install as volta support for pnpm is not added yet.
|
||||
# npx is required for first install because volta does not support pnpm yet
|
||||
npx pnpm install
|
||||
```
|
||||
|
||||
### 3. Verify Everything Is Working
|
||||
|
||||
Once you have installed pnpm, you can run the `test` script to verify that pnpm is working _and_ that the repository has been cloned correctly:
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
**The Docs Structure is dictated by [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**
|
||||
The `test` script and others are in the top-level `package.json` file.
|
||||
|
||||
## 3. Contributing Code
|
||||
## Contributing Code
|
||||
|
||||
The basic steps for contributing code are:
|
||||
|
||||
1. Create 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._
|
||||
1. **Create** 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._
|
||||
|
||||
### 1. Create a git branch for your work
|
||||
|
||||
Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching.
|
||||
[TODO - mermaid git diagram here]
|
||||
|
||||
Development is done in the `develop` branch.
|
||||
|
||||
Once development is done we branch a `release` branch from `develop` for testing.
|
||||
@@ -146,6 +165,7 @@ it('should render forks and joins', () => {
|
||||
```
|
||||
|
||||
[TODO - running the tests against what is expected in development. ]
|
||||
|
||||
[TODO - how to generate new screenshots]
|
||||
....
|
||||
|
||||
@@ -176,7 +196,7 @@ we have put in place a process, wherein _knsv, Knut Sveidqvist_ is the primary r
|
||||
|
||||
**Reminder: Pull Requests should be directed to the develop branch.**
|
||||
|
||||
## 4. Contributing Documentation
|
||||
## Contributing Documentation
|
||||
|
||||
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?
|
||||
|
||||
@@ -194,6 +214,8 @@ We are a little less strict here, it is OK to commit directly in the `develop` b
|
||||
|
||||
The documentation is located in the `src/docs` directory and organized according to relevant subfolder.
|
||||
|
||||
**The Docs Structure is dictated by [sidebar.md](https://github.com/mermaid-js/mermaid/edit/develop/src/docs/_sidebar.md)**
|
||||
|
||||
The `docs` folder will be automatically generated when committing to `src/docs` and should not be edited manually.
|
||||
|
||||
We encourage contributions to the documentation at [mermaid-js/mermaid/src/docs](https://github.com/mermaid-js/mermaid/tree/develop/src/docs). We publish documentation using GitHub Pages with [Docsify](https://www.youtube.com/watch?v=TV88lp7egMw&t=3s)
|
||||
@@ -231,7 +253,7 @@ To edit Docs on GitHub:
|
||||
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.
|
||||
|
||||
## 5. Have Questions or Suggestions?
|
||||
## Have Questions or Suggestions?
|
||||
|
||||
#### First search to see if someone has already asked (and hopefully been answered) or suggested the same thing.
|
||||
|
||||
@@ -250,7 +272,7 @@ Log in to [GitHub.com](https://www.github.com), open or append to an issue [usin
|
||||
|
||||
### How to Contribute a Suggestion
|
||||
|
||||
## 6. Last Words
|
||||
## 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user