From 0cd911b4fd48c7d173cf5718f3033ce4283b3e25 Mon Sep 17 00:00:00 2001
From: damithc <>
Date: Sun, 14 Jun 2020 01:40:17 +0800
Subject: [PATCH 1/3] Refactor developer docs
Let's refactor the dev docs in the following ways to improve the
overall organization:
* Split up into separate pages such as setting up, design, workflow etc.
* Refer to se-education.org/guides when possible
* Improve phrasing, layout, formatting
This reorganization also aim to increase consistency with other
sister projects such as RepoSense
---
docs/_markbind/layouts/devGuide/navigation.md | 11 +-
docs/devGuide/contributing.md | 73 ----
docs/devGuide/contributing/code-of-conduct.md | 82 ----
docs/devGuide/design.md | 69 ++++
docs/devGuide/devGuide.md | 264 +------------
docs/devGuide/maintainerGuide.md | 360 ------------------
docs/devGuide/projectManagement.md | 341 +++++++++++++++++
docs/devGuide/settingUp.md | 43 +++
docs/devGuide/styleGuides.md | 20 +
docs/devGuide/workflow.md | 120 ++++++
10 files changed, 619 insertions(+), 764 deletions(-)
delete mode 100644 docs/devGuide/contributing.md
delete mode 100644 docs/devGuide/contributing/code-of-conduct.md
create mode 100644 docs/devGuide/design.md
delete mode 100644 docs/devGuide/maintainerGuide.md
create mode 100644 docs/devGuide/projectManagement.md
create mode 100644 docs/devGuide/settingUp.md
create mode 100644 docs/devGuide/styleGuides.md
create mode 100644 docs/devGuide/workflow.md
diff --git a/docs/_markbind/layouts/devGuide/navigation.md b/docs/_markbind/layouts/devGuide/navigation.md
index a42eee2bb6..2cf7cae2a4 100644
--- a/docs/_markbind/layouts/devGuide/navigation.md
+++ b/docs/_markbind/layouts/devGuide/navigation.md
@@ -2,8 +2,11 @@
Developer Guide
-* [Developer Guide]({{baseUrl}}/devGuide/devGuide.html)
-* [Maintainer Guide]({{baseUrl}}/devGuide/maintainerGuide.html)
-* [Contributing]({{baseUrl}}/devGuide/contributing.html)
- * [Code of Conduct]({{baseUrl}}/devGuide/contributing/code-of-conduct.html)
+* [Contributing]({{baseUrl}}/devGuide/devGuide.html)
+* [Setting up]({{baseUrl}}/devGuide/settingUp.html)
+* [Workflow]({{baseUrl}}/devGuide/workflow.html)
+* [Design]({{baseUrl}}/devGuide/design.html)
+* [Project management]({{baseUrl}}/devGuide/projectManagement.html)
+* Appendices :expanded:
+ * [Style guides]({{baseUrl}}/devGuide/styleGuides.html)
diff --git a/docs/devGuide/contributing.md b/docs/devGuide/contributing.md
deleted file mode 100644
index ad62363f52..0000000000
--- a/docs/devGuide/contributing.md
+++ /dev/null
@@ -1,73 +0,0 @@
-
- title: "Contributing"
- layout: devGuide
- pageNav: default
-
-
-# Contributing to MarkBind
-
-Thank you for your interest in contributing! We're glad you want to help. Read the sections below to learn about our code of conduct and how to get started contributing.
-
-## Code of conduct
-
-This project and everyone participating in it are governed by our [Code of Conduct]({{baseUrl}}/devGuide/contributing/code-of-conduct.html). By participating, you are expected to uphold this code. Please report unacceptable behavior to markbind@comp.nus.edu.sg.
-
-## Things to do before getting started
-
-Make sure you have the project set up and ready. We have guides detailing what we [expect our contributors to know]({{baseUrl}}/devGuide/devGuide.html#requirement), our required [environment]({{baseUrl}}/devGuide/devGuide.html#environment) and our [development process]({{baseUrl}}/devGuide/devGuide.html#development-process).
-
-## How to contribute
-
-All contributions are welcome. You can contribute to MarkBind by:
-- Reporting bugs
-- Requesting features
-- Making changes (with a corresponding Pull Request), by:
- - Updating documentation
- - Fixing bugs
- - Implementing features
-
-### How to report a bug
-
-Report bugs in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guideslines below. This helps us in undestanding your report.
-
-- Before reporting a bug, please search if someone else has has already reported it in the [existing issues](https://github.com/MarkBind/markbind/issues).
-- Is your bug from the current version or an older version of MarkBind? What OS are you on? Tell us about your environment, for example, the MarkBind version you are on.
-- What did you do? What did you expect to happen? What actually happened?
- - Include things such the actual MarkBind code causing the issue, the steps for reproduction, the raw output, and what you expect instead can help us in diagnosing the issue quicker
- - You are also encouraged to submit a PR that reproduces this in `test/functional/test_site/bugs/`.
-
-Please do not submit personal support requests (eg: "How do I use X?") as bugs. Instead, feel free to [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker with a label of question.
-
-### How to request a feature
-
-We welcome suggestions to improve MarkBind as well. To do so, you can request for new features or enhancements to existing features in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guidelines below. This helps us in undestanding your request.
-
-- Before requesting a new feature, please search if someone else has has already requested for it in the [existing issues](https://github.com/MarkBind/markbind/issues).
-- Is your request related to a problem? Provide a clear and concise description of what the problem is.
- Eg: I have an issue when [...]
-- Describe the solution you'd like. Provide a clear and concise description of what you want to happen.
-- Describe alternatives you've considered. Let us know about other solutions you've tried or researched.
-- You can also share some additional context, anything else that you can add about the proposal.
-
-### First issues for contributors
-
-Unsure where to begin contributing to MarkBind?
-
-We recommend that you start off by visiting the [Getting Started](https://markbind.org/userGuide/gettingStarted.html) section in the User Guide and try out MarkBind as a user. Exploring and understanding the various features it provides.
-
-If you have not done so yet, we also recommend visiting the [Developer Guide]({{baseUrl}}/devGuide/index.html) to learn about the [structure of the project]({{baseUrl}}/devGuide/index.html#project-structure), how to set up the [developer environment]({{baseUrl}}/devGuide/index.html#development-process), and how to run [tests]({{baseUrl}}/devGuide/devGuide.html#testing).
-
-When you're ready, you can start by looking through these issues marked good first issue.
-
-If you have any questions, be it regarding MarkBind or our workflow, feel free to [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker with a label of question.
-
-### How to make Pull Requests to submit changes?
-
-Please follow the steps to have your contribution considered by the maintainers:
-
-1. Follow all the instructions in the pull request [template](https://github.com/MarkBind/markbind/blob/master/.github/PULL_REQUEST_TEMPLATE), the same template is also given to you when you submit a new Pull Request.
-2. After you submit your pull request, verify that all [status checks](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks) are passing
-3. You can then [request for a review](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/requesting-a-pull-request-review)
- - Not sure who to ask a review from? A good rule of thumb is to check recently [merged](https://github.com/MarkBind/markbind/pulls?q=is%3Apr+is%3Aclosed) or [approved](https://github.com/MarkBind/markbind/pulls?q=is%3Aopen+is%3Apr+review%3Aapproved) pull requests, and see who the reviewers are. It's likely that they are currently active and willing to review your pull request as well!
-
-Reviewer(s) may request additional changes from you in terms of implementation, design, tests, style, or other changes before your pull request is finally approved.
\ No newline at end of file
diff --git a/docs/devGuide/contributing/code-of-conduct.md b/docs/devGuide/contributing/code-of-conduct.md
deleted file mode 100644
index 077413c21d..0000000000
--- a/docs/devGuide/contributing/code-of-conduct.md
+++ /dev/null
@@ -1,82 +0,0 @@
-
- title: "Code of Conduct"
- layout: devGuide
- pageNav: default
-
-
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
- advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
- address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
- professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at markbind@comp.nus.edu.sg. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
diff --git a/docs/devGuide/design.md b/docs/devGuide/design.md
new file mode 100644
index 0000000000..83f7755bf0
--- /dev/null
+++ b/docs/devGuide/design.md
@@ -0,0 +1,69 @@
+Design
+
+ title: "{{ title }}"
+ layout: devGuide
+ pageNav: default
+
+
+# {{ title }}
+
+
+
+This page gives you an overview of the MarkBind's internal design.
+
+
+## Project structure
+
+MarkBind project consists of two repos:
+
+* [MarkBind](https://github.com/MarkBind/markbind)
+
+ * The command-line interface (CLI) application that accepts commands from users, and uses the core library to parse and generate web pages resides in the root.
+
+ * The core library that resolves the content include path, and the rendering of Markdown contents resides in the `lib/markbind/` directory.
+
+ Stack used: *Node.js*
+
+* [VueStrap library (forked version modified for MarkBind)](https://github.com/MarkBind/vue-strap)
+
+ * The UI components library used in MarkBind project. Users could use it in their contents to create complex and interactive structure.
+
+ Stack used: *Vue.js*
+
+### MarkBind core library
+
+The core library parses the given Markdown file, processes all the content include, and renders all Markdown into HTML so that it could be displayed in a browser.
+
+All the core logic resides inside the `lib/parser.js` file. It exposes two important APIs: **include** and **render**.
+
+*Include* and *Render* will first parse the given file as a DOM tree, and then recursively visit every node to check if it needs special handling.
+
+In the *Include* stage, it will check if the node will include new contents (for example, if it is an "include" tag (``), and then load the file/content to be included into the current working context. For the new content included, the *Include* step will be run recursively until all the content to be included are resolved and loaded.
+
+*Render* is a similar process to *Include*, but it will render the content recursively to ensure all Markdown are converted to HTML.
+
+MarkBind uses [markdown-it](https://github.com/markdown-it/markdown-it) to do the Markdown parsing and rendering. There are also several customized markdown-it plugins used in MarkBind, which are located inside the `lib/markdown-it/` directory.
+
+### MarkBind CLI
+
+The CLI application handles the site generation logic. It contains the command handling logic, as well as the Site and Page models.
+
+The site generation logic is as follows:
+
+1. Read the project's `site.json` file to collect all pages that will be generated.
+2. Create a Site model, where the site's root path is where `site.json` is located. The site model knows all the pages it contains, as well as the static assets. Static assets, such as stylesheets and JavaScript libraries, will be scanned and filtered, and then copied to the generated site folder (`_site/`).
+3. The Site model will create different Page models, and each Page model will generate a HTML page at the designated file location by calling MarkBind core library's *include* and *render* APIs.
+
+The generated page is rendered using [nunjucks](https://mozilla.github.io/nunjucks/), and the page template could be found at `lib/template/page.njk`.
+
+Static assets of MarkBind, such as stylesheets and JavaScript libraries, are located in `asset/` folder. They will be copied to the generated site and used in the generated pages. For each version update of VueStrap, copy the built library file to overwrite `asset/js/vue-strap.min.js`.
+
+The CLI program is built using [commander.js](https://github.com/tj/commander.js/).
+
+The auto deployment library used is [gh-pages](https://github.com/tschaub/gh-pages).
+
+### VueStrap
+
+The VueStrap library is [Bootstrap](getbootstrap.com/components/) components rewritten in [Vue.js](vuejs.org). We forked it from the original repo, and changed it based on our needs for educational websites.
+
+You can find more information at the [VueStrap repo](https://github.com/MarkBind/vue-strap).
diff --git a/docs/devGuide/devGuide.md b/docs/devGuide/devGuide.md
index 1eb18c55c5..5c16b54e54 100644
--- a/docs/devGuide/devGuide.md
+++ b/docs/devGuide/devGuide.md
@@ -1,260 +1,34 @@
+Contributing
- title: "Developer Guide"
+ title: "{{ title }}"
layout: devGuide
- pageNav: default
-## Requirement
+
Developer guide
-We expect contributors for MarkBind to have basic knowledge of the following:
+# {{ title }}
+
+
+**Thank you for your interest in contributing!** We're glad you want to help. We welcome PRs, especially from students.
+
+
+**First, do take note of** [**our _code of conduct_** (from SE-EDU)](https://se-education.org/guides/guidelines/codeOfConduct.html). Reporting bugs or submitting feature suggestions in [our issue tracker](https://github.com/markbind/markbind) can help too.
+
+**Second, ensure you have a basic knowledge** of the following:
* JavaScript (ES6)
-* Node.js (LTS or higher) [with npm version of 6.12.1 or higher]
+* Node.js
* HTML & CSS
* Markdown
* Command-line environment
-## Environment
-
-The MarkBind project should be developed with Node.js version 8.0 or higher.
-
-We recommend you to use WebStorm for a better development experience.
-
-Use JavaScript ES6 features if possible for better performance, e.g. Promise instead of callback.
-
-## Project Structure
-
-MarkBind project consists of two repos:
-
-* [MarkBind](https://github.com/MarkBind/markbind)
-
- * The command-line interface (CLI) application that accepts commands from users, and uses the core library to parse and generate web pages resides in the root.
-
- * The core library that resolves the content include path, and the rendering of Markdown contents resides in the `lib/markbind/` directory.
-
- Stack used: *Node.js*
-
-* [VueStrap library (forked version modified for MarkBind)](https://github.com/MarkBind/vue-strap)
-
- * The UI components library used in MarkBind project. Users could use it in their contents to create complex and interactive structure.
-
- Stack used: *Vue.js*
-
-### MarkBind Core Library
-
-The core library parses the given Markdown file, processes all the content include, and renders all Markdown into HTML so that it could be displayed in a browser.
-
-All the core logic resides inside the `lib/parser.js` file. It exposes two important APIs: **include** and **render**.
-
-*Include* and *Render* will first parse the given file as a DOM tree, and then recursively visit every node to check if it needs special handling.
-
-In the *Include* stage, it will check if the node will include new contents (for example, if it is an "include" tag (``), and then load the file/content to be included into the current working context. For the new content included, the *Include* step will be run recursively until all the content to be included are resolved and loaded.
-
-*Render* is a similar process to *Include*, but it will render the content recursively to ensure all Markdown are converted to HTML.
-
-MarkBind uses [markdown-it](https://github.com/markdown-it/markdown-it) to do the Markdown parsing and rendering. There are also several customized markdown-it plugins used in MarkBind, which are located inside the `lib/markdown-it/` directory.
-
-### MarkBind CLI
-
-The CLI application handles the site generation logic. It contains the command handling logic, as well as the Site and Page models.
-
-The site generation logic is as follows:
-
-1. Read the project's `site.json` file to collect all pages that will be generated.
-2. Create a Site model, where the site's root path is where `site.json` is located. The site model knows all the pages it contains, as well as the static assets. Static assets, such as stylesheets and JavaScript libraries, will be scanned and filtered, and then copied to the generated site folder (`_site/`).
-3. The Site model will create different Page models, and each Page model will generate a HTML page at the designated file location by calling MarkBind core library's *include* and *render* APIs.
-
-The generated page is rendered using [nunjucks](https://mozilla.github.io/nunjucks/), and the page template could be found at `lib/template/page.njk`.
-
-Static assets of MarkBind, such as stylesheets and JavaScript libraries, are located in `asset/` folder. They will be copied to the generated site and used in the generated pages. For each version update of VueStrap, copy the built library file to overwrite `asset/js/vue-strap.min.js`.
-
-The CLI program is built using [commander.js](https://github.com/tj/commander.js/).
-
-The auto deployment library used is [gh-pages](https://github.com/tschaub/gh-pages).
-
-### VueStrap
-
-The VueStrap library is [Bootstrap](getbootstrap.com/components/) components rewritten in [Vue.js](vuejs.org). We forked it from the original repo, and changed it based on our needs for educational websites.
-
-You can find more information at the [VueStrap repo](https://github.com/MarkBind/vue-strap).
-
-## Development Process
-
-### Prerequisite
-
-MarkBind requires the following dependencies:
-
-* Node.js (LTS or higher) [with npm version of 6.12.1 or higher]
-* Java 8 or later (required to run the PlantUML JAR executable)
-* Graphviz v2.38 or later (required to generate PlantUML diagrams)
-
-Before cloning MarkBind's repo, run
-
-* `node --version` for Node.js
-* `npm --version` for NPM
-* `java --version` for Java
-* `dot -V` for Graphviz
-
-to make sure that you have all necessary dependencies installed and accessible in the path variable.
-
-### Development
-
-1. Fork and clone the MarkBind repo.
-
-2. In the folder of your cloned repo, run
-
- ```
- $ npm install
- ```
-
- to install the project dependencies.
-
-3. To make sure you are using the cloned CLI program in your own terminal/console, in the cloned CLI repo, run
-
- ```
- $ npm link
- ```
-
- to bind the local MarkBind CLI program to the cloned development version.
-
-4. Now you can start making changes.
-
-#### Troubleshooting
-
-**Q: When I build a MarkBind website, I get strange errors relating to HTML tags in .md/.mbd files. For example:**
-
-```
-TypeError: Cannot set property 'src' of null
- at Page.collectFrontMatter (~\markbind\src\Page.js:399:26)
-```
-
-A: Please report this in a [new issue](https://github.com/MarkBind/markbind/issues/new), since this should already be fixed by [MarkBind/markbind#948](https://github.com/MarkBind/markbind/pull/948).
-
-### Testing
-
-Our test script does the following:
-
-1. Lints the code for any code and style errors using ESLint.
-1. Builds the test sites whose directory names are listed in `test/functional/test_site`.
-1. For each test site, compares the HTML files generated with the HTML files in its `expected` directory.
-
-#### Running tests
-
-To execute the tests, simply run:
-
-For Unix:
-
-```
-$ npm run test
-```
-
-For Windows users:
-
-```
-> npm run testwin
-```
-
-#### Updating tests
-
-Whether you are adding a new feature, updating existing features or fixing bugs, make sure to update the test sites to reflect the changes.
-
-You may use the following script to do this:
-
-On Unix:
-
-```
-$ npm run updatetest
-```
-
-On Windows:
-
-```
-> npm run updatetestwin
-```
-
- You should always check that the generated output is correct before committing any changes to the test sites.
-
-
-#### Adding test site content
-
-When adding new features, you should also add new site content into an existing test site or create a new test site to demonstrate the new feature. This is to ensure that your feature can be tested by building that test site.
-
-To add a page to an existing test site, for this example, to `test_site`:
-
-1. Add a new test page, e.g., `newTestPage.md`, containing a demonstration of the new feature.
-
-2. Open the `site.json` corresponding to the test site, i.e. `test/functional/test_site/site.json`
-
-3. To include the new page, i.e. `newTestPage.md`, add it to the `pages` array.
-
-``` {heading="site.json" highlight-lines="16,17"}
-"pages": [
- {
- "src": "index.md",
- "title": "Hello World",
- "frontmatter": {
- "frontMatterOverrideProperty": "Overridden by front matter override",
- "globalAndFrontMatterOverrideProperty": "Overridden by front matter override"
- }
- },
- ...
- {
- "src": "testLayouts.md",
- "title": "Hello World"
- },
- {,
- "src": "newTestPage.md",
- "title": [some title you see fit]
- },
- ...
-```
-
-4. Update the tests using `npm run updatetest`.
-
-
- When creating a new test site, the directory name of the new test site should be added to `test/functional/test_sites` file.
-
-
-### Using ESLint
-
-Our projects follow a [coding standard](https://github.com/oss-generic/process/blob/master/docs/CodingStandards.adoc). Using a linter will help check and fix some of the code style errors in your code. It will save time for both you and your code reviewer. The linting tool we use is [ESLint](https://eslint.org/). Here is a [gist](https://gist.github.com/nicholaschuayunzhi/bfe53dbb5f1a0f02d545d55956f9ab7e) with an explanation of the ESLint rules chosen in markbind-cli.
-
-#### Installation
-
-Install developer dependencies (ESLint, related plugins) in your cloned markbind and markbind-cli repositories.
-
-```
-$ npm install --only=dev
-```
-
-#### Lint your code
-
-Before making a commit or pull request, you should lint your code.
-
-To lint a specific file, go to the root directory of the cloned repo and run
-
-```
-$ ./node_modules/.bin/eslint path/to/specificfile.js
-```
-
-To lint all files, run
-
-```
-$ ./node_modules/.bin/eslint .
-```
-
-You can add the `--fix` flag to correct any fixable style errors.
-
-```
-$ ./node_modules/.bin/eslint . --fix
-```
+**Third, ensure you have spent time with MarkBind and familiar with the content of the [user guide](../userGuide).** It's important to know the product well before you start contributing code.
-You may also correct fixable style errors for both JavaScript and CSS, by running this npm script
-```
-$ npm run autolint
-```
+**Now, follow these steps to get started on contributing:**
-#### Integration with editors
+1. **Set up the project** in your computer (see [the _Setting up_ page](settingUp.html))
+1. **Learn our workflow** (see [the _Workflow_ page](workflow.html))
+1. **Submit PRs** as per the workflow. If you encounter any problems, post in [our issue tracker](https://github.com/markbind/markbind/issues).
-ESLint has [integrations with popular editors](https://eslint.org/docs/user-guide/integrations). They offer features such as "fix errors on save", which will make developement more convenient.
+**We look forward to your PR. Happy coding!**
diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md
deleted file mode 100644
index ae1642fdf2..0000000000
--- a/docs/devGuide/maintainerGuide.md
+++ /dev/null
@@ -1,360 +0,0 @@
-
- title: "Maintainer Guide"
- layout: devGuide
- pageNav: default
-
-
-# PR Merging Workflow
-
-## Approval
-
-* Once the first approval is given from a developer, assign a version milestone to the PR (this is usually the next version, unless there is a justification for delaying the merging to future versions).
- * **Note:** Should there be a subsequent rejection by other reviewers (or an error is spotted), the version milestone is removed immediately. The version milestone should only be restored once the new approvals come in.
-* Once the second approval is given from a senior developer (or there are >= 3 approvals given from anyone), the PR can be merged immediately.
- * If there is no second approval yet, please wait for a day before merging the PR without the second approval.
- * **Rationale:** This is to allow other developers the chance to review the PR, and delay the merge if there's any significant problems. Not everyone is available all of the time, so please be patient.
- * **Note:** If the PR is too simple (e.g. correcting a simple typo), one approval is sufficient for merging, and this requirement is relaxed.
-
-## Actual Merging
-
-1. Re-run the Travis build for the current PR's `continuous-integration/travis-ci/pr`.
- * **Rationale:** This is because we do not ask PR authors to rebase their PRs, but the master branch may have since been updated. It is possible for tests to pass on their branch, only to fail when integrating the changes with the master (**Note:** This is possible even if GitHub _doesn't_ complain about any merge conflict!)
-2. Merge the PR. Depending on the PR:
- * Use "Squash and Merge" if the PR is a simple feature.
- * Use "Create a Merge Commit" if the PR is non-trivial, and the author has tidied up the commit organization so that each commit is a logical change.
-
- a. Regardless of the option chosen above, ensure that your commit title is of the form ` (#PR_NUMBER)`. For example, for PR #745, it is of the form:
-
- `Add built-in support for light themes from bootswatch (#745)`
-
- b. For non-trivial PRs, ensure that there is a sensible commit message accompanied by it. **Rationale:** So that future developers have an idea of what is going on for this PR without having to go back to the GitHub website.
-
- c. Before confirming the merge, do ensure that no other PRs have been merged to master **since the time you started drafting the merging commit's title and message**. Otherwise, you may face a glitch where GitHub merges your PR without squashing. (Reference: [MarkBind#1160](https://github.com/MarkBind/markbind/pull/1160))
-
-Please follow the [commit message convention](https://oss-generic.github.io/process/docs/FormatsAndConventions.html#commit-message). For example, for PR #745, the commit message is as follows:
-
- ```
- To use any custom Bootstrap themes, authors must manually copy over the
- theme's .css files to the website's asset folders, and configure the
- layout's head.md to use the .css files.
-
- Let's add built-in support for bootswatch light themes, by providing a
- "theme" option in site.json, so that authors can just directly specify
- the name of the theme in order to use it. For example:
-
- {
- "theme": "bootswatch-cerulean"
- }
-
- Dark themes from Bootswatch are not yet supported because they require
- our custom MarkBind components to inherit the Bootstrap styling classes,
- to be done in #782.
- ```
-
-3. Ensure that a version milestone is tagged to the PR. **Reason:** We may have missed it during the "Approval" stage, so please add the version milestone if it is missing, so that the drafting of the release notes during the release process will be easier.
-
-# Doing a Release
-
-## Prerequisites for New Maintainers
-
-Ensure that:
-
-* You have the rights to push to master branch on [MarkBind's repository](https://github.com/MarkBind/markbind), and also to make new releases.
-* You have the rights on [npm](https://www.npmjs.com/) to make a new release.
- * You need to login to npm on your terminal with `npm adduser` first, before you can publish packages to npm.
-
-## Building Vue-Strap
-1. Navigate to the root directory for vue-strap, then ensure that all dependencies are updated by executing:
-
-```
-$ npm install
-```
-
-2. Build the assets by executing:
-
-```
-$ npm run build
-```
-
-You should see changes in `vue-strap.min.js`.
-
-* **Note:** Building vue-strap is optional if there's no changes since the last release of MarkBind. If there are no changes to the three files mentioned above, skip to the "Building MarkBind" section.
-
-* **Note:** Do take a glance at the diff for `vue-strap.min.js` to see if there's any strange changes (e.g. the version of jQuery changes even though no one upgraded it).
-
-3. Commit the new changes.
-
-```
-$ git commit -am 'Update dist'
-```
-
-4. Tag the new commit with the new version number, whereby `XYZ` is the incremented number of the previous release.
-
-```
-$ git tag v2.0.1-markbind.XYZ
-```
-
-* **Note:** The tag used is a lightweight tag. _Don't_ use an annotated tag.
-
-5. Push everything to the main vue-strap repository (replace `XYZ` with version number).
-
-```
-$ git push upstream master
-$ git push upstream v2.0.1-markbind.XYZ
-```
-
-## Building MarkBind
-1. Navigate to the root directory for MarkBind, then ensure that all dependencies are updated by executing:
-
-```
-$ npm install
-```
-
-2. If we did a new vue-strap release, then:
-
- a. Copy `vue-strap.min.js` from the vue-strap repository to the main asset folder, and to each of the test site's `expected/` folder.
-
-```
-# copy to main asset folder
-$ cp /dist/vue-strap.min.js /asset/js/vue-strap.mins.js
-
-# for each test site's expected folder:
-$ cp /dist/vue-strap.min.js /test/functional//expected/markbind/js/vue-strap.min.js
-```
-
-b. Commit the new vue-strap assets (replace `XYZ` with version number).
-
-```
-$ git commit -m 'Update vue-strap version to v2.0.1-markbind.XYZ'
-```
-
-* **Note:** We uniquely do this for each MarkBind release (rather than spontaneously update the vue-strap files for each affected PR), in order to reduce unnecessary merge conflicts. It also makes it easier for the maintainers to vet the changes.
-
-3. Run `npm version` to increment the version number. Which to increment (`patch`, `minor` or `major`) depends on what PRs are merged for the new version, which means you must know beforehand about the changes.
-
-* If there are no significant changes, a `patch` is sufficient:
-
-```
-$ npm version patch
-```
-
-* If there are significant changes (e.g. breaking changes, new release), a `minor` release is needed:
-
-a. Run `npm version minor` as per normal.
-
-b. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. (Note: You do not have to commit these changes immediately, as we also have to rebuild the test files in the next step anyway.)
-
-```
-$ npm version minor
-```
-
-* We rarely do `major` releases, but if necessary, the steps are the same as the `minor` release (just change `minor` to `major`).
-
-4. Rebuild the test files.
-
-```
-# on Unix
-$ npm run updatetest
-
-# on Windows
-> npm run updatetestwin
-```
-
-When rebuilding the expected test files, ensure that **only** the version number is updated. For example, this is correct:
-
-```diff
-diff --git a/test/functional/test_site/expected/bugs/index.html b/test/functional/test_site/expected/bugs/index.html
-index 779f279..bb3c602 100644
---- a/test/functional/test_site/expected/bugs/index.html
-+++ b/test/functional/test_site/expected/bugs/index.html
-@@ -4,7 +4,7 @@
-
-
-
--
-+
-
- Open Bugs
-
-```
-
-However, if there are any extra lines changed, that means that someone screwed up the functional tests, and needs to be fixed accordingly!
-
-5. The changes that you have made in the last two steps need to be combined together with the version commit generated by `npm version`. Therefore, amend the version commit and version tag by doing the following (change `vA.B.C` to the new version's string accordingly).
-
-```
-$ git commit -a --amend --reuse-message vA.B.C
-$ git tag --force vA.B.C # to reassign the tag to the newly amended commit
-```
-
-6. Push the new commit and version tag generated by `npm` (change `vA.B.C` to the new version's string accordingly).
-
-```
-$ git push upstream master
-$ git push upstream vA.B.C
-```
-
-7. Run `npm publish`. You should receive a notification by `npm` that the publish is successful.
-
-```
-$ npm publish
-```
-
-8. If you used `npm link` for your project, ensure that you try the new release on another platform that doesn't use `npm link`, so that we can be sure the end-users can install and use the new version.
-
- a. Just do `npm i -g markbind-cli@A.B.C` on the different platform and...
-
- b. ... play around with the new MarkBind version to ensure that it works.
-
-9. Ensure that the documentation at markbind.org is deployed correctly.
-
-Since [#701](https://github.com/markbind/markbind/pull/701), the deployment is automated.
-
-However, if it doesn't deploy properly for the release, do the following:
-
-```
-$ cd docs
-$ markbind build
-$ markbind deploy
-```
-
-10. Close the [issue milestone on GitHub](https://github.com/MarkBind/markbind/milestones) tied to that version.
-
- a. Please also create a new milestone for the next iterations. Recommended to have at least two version milestones opened.
-
-11. Draft a new release on GitHub.
-
- a. Go to the Markbind release page at https://github.com/MarkBind/markbind/releases.
-
- b. Click "Draft a new release".
-
- c. For the tag version, enter `vA.B.C`. (The newly released version should be recognized by GitHub, with an "Existing Tag" indicator, otherwise, ensure that you have pushed the version commit and tag in step 4).
-
- d. For the release title, leave it blank.
-
- e. For the main body, use the following template:
-
-```markdown
-# markbind-cli
-
-
-
-
-## User Facing Changes
-
-### Breaking Changes
-
-
-
-> Also give a brief explanation note about:
-> - what was the old feature that was made obsolete
-> - any replacement feature (if any), and
-> - how the author should modify his website to migrate from the old feature to the replacement feature (if possible).
-
-### Features
-
-
-
-### Enhancements
-
-
-
-### Fixes
-
-
-
-### Documentation
-
-
-
-## Other Changes
-
-### Code Quality
-
-
-
-### DevOps Changes
-
-
-
-### Dependencies
-
-
-
-[MarkBind/vue-strap](https://github.com/MarkBind/vue-strap): v2.0.1-markbind.OLD → v2.0.1-markbind.NEW
-
-### Miscellaneous
-
-
-
-```
-
-Use the list of PRs merged in the milestone to write the release notes. You may omit any sections that do not have a single PR under it.
-
-An example of a release note draft (taken from v1.18.0):
-
-```
-# markbind-cli
-
-### Breaking Changes
-
-#653 Disable decamelize for anchor ID generation (#667, MarkBind/vue-strap#95)
-
-> Headings with PascalCase wordings now generate a different anchor ID
-in order to be more compatible with anchor IDs generated by Github
-Flavored Markdown.
->
-> For example, if we have the following heading:
->
-> ```markdown
-> # MarkBind docs
-> ```
->
-> Old anchor id:
->
-> ```
-> mark-bind-docs
-> ```
->
-> **New** anchor id:
->
-> ```
-> markbind-docs
-> ```
->
-
-### Features
-
-#457 Add `deploy -t/--travis` to deploy via Travis (#649)
-#470 Support custom MarkBind plugins (#474)
-#642 Support specifying include variables inline (#681)
-
-### Enhancements
-
-#369 Seamless panels: omit caret if not expandable (MarkBind/vue-strap#96)
-#657 Add temporary styles to prevent FOUC (#664)
-
-### Fixes
-
-#651 Exit MarkBind with non-zero exit code on fatal error (#679)
-
-### Documentation
-
-Restructure user docs on MarkBind syntax (#668)
-Add documentation for badges (#686)
-Fix filename capitalization for syntax documentation (#685)
-
-### Code Quality
-
-test: Add diff printing for easier debugging (#632)
-
-### Dependencies
-
-[MarkBind/vue-strap](https://github.com/MarkBind/vue-strap): v2.0.1-markbind.20 → v2.0.1-markbind.21
-```
-
-f. Click "Publish release".
-
-12. Finally, announce the new release on our Slack channel (replace `A.B.C` with the new version). Congrats!
-
-* Published: `npm i -g markbind-cli@A.B.C`
diff --git a/docs/devGuide/projectManagement.md b/docs/devGuide/projectManagement.md
new file mode 100644
index 0000000000..69c74d2852
--- /dev/null
+++ b/docs/devGuide/projectManagement.md
@@ -0,0 +1,341 @@
+Project management
+
+ title: "{{ title }}"
+ layout: devGuide
+ pageNav: default
+
+
+# {{ title }}
+
+
+
+This page contains information about project management tasks. The target audience is senior developers (and above).
+
+
+## Managing PRs
+
+For general best practices, refer to the guide [_Working with PRs_ @SE-EDU](https://se-education.org/guides/guidelines/PRs.html).
+
+### Approval
+
+* **If the PR is very simple** (e.g. correcting a simple typo), one approval is sufficient for merging. Other PRs need two approvals.
+
+* **Once the first approval is given** from a developer, assign a version milestone to the PR (this is usually the next version, unless there is a justification for delaying the merging to future versions).
+
+
+
+ **Note:** Should there be a subsequent rejection by other reviewers (or an error is spotted), the version milestone is removed immediately. The version milestone should only be restored once the new approvals come in.
+
+
+* **Once the second approval is given** from a ==senior developer== (or there are >= 3 approvals given from anyone), the PR can be merged immediately.
+ If there is no second approval yet, wait for a day before merging the PR without the second approval.
+
+
+
+ This is to allow other developers the chance to review the PR, and delay the merge if there's any significant problems. Not everyone is available all of the time, so please be patient.
+
+
+### Merging
+
+1. **Re-run the Travis build** for the current PR's `continuous-integration/travis-ci/pr`.
+
+
+
+ **Rationale:** This is because we do not ask PR authors to rebase their PRs, but the master branch may have since been updated. It is possible for tests to pass on their branch, only to fail when integrating the changes with the master
+
+ This is possible even if GitHub _doesn't_ complain about any merge conflict!
+
+1. **Merge the PR**.
+ * Refer the guide [_Working with PRs_ @SE-EDU](https://se-education.org/guides/guidelines/PRs.html) which merge strategy to use (i.e., squash, rebase, merge commit)
+
+ * Format for the merge/squashed commit title: `PR_TITLE (#PR_NUMBER)`
+ `Add built-in support for light themes from bootswatch (#745)`
+
+ * For non-trivial PRs, ensure that there is a sensible commit message accompanied by it. Both the title and the body should follow the [_Git conventions_ @SE-EDU](https://se-education.org/guides/conventions/git.html).
+
+ * Before confirming the merge, do ensure that no other PRs have been merged to master _since the time you started drafting the merging commit's title and message_. Otherwise, you may face a glitch where GitHub merges your PR without squashing. (Reference: [MarkBind#1160](https://github.com/MarkBind/markbind/pull/1160))
+
+1. **Set a milestone** to the PR.
+
+
+
+ **Reason:** We may have missed it during the "Approval" stage, so please add the version milestone if it is missing, so that the drafting of the release notes during the release process will be easier.
+
+
+## Doing a Release
+
+
+
+ **Attention new maintainers!** Ensure that:
+
+* You have the rights to push to master branch on [MarkBind's repository](https://github.com/MarkBind/markbind), and also to make new releases.
+* You have the rights on [npm](https://www.npmjs.com/) to make a new release.
+ You need to login to npm on your terminal with `npm adduser` first, before you can publish packages to npm.
+
+
+### Building Vue-Strap
+
+1. **Navigate to the root** directory for vue-strap
+1. **Update dependencies** by running `npm install`
+1. **Build the assets** by executing `npm run build` after which you should see changes in `vue-strap.min.js`.
+
+
+
+ Building vue-strap is optional if there's no changes since the last release of MarkBind. If there are no changes to the three files mentioned above, skip to the "Building MarkBind" section.
+
+
+
+ Do take a peek at the diff for `vue-strap.min.js` to see if there's any strange changes (e.g. the version of jQuery changes even though no one upgraded it).
+
+
+1. **Commit** the new changes (`git commit -am 'Update dist'`)
+
+1. **Tag** the new commit with the new version number, whereby `XYZ` is the incremented number of the previous release.
+ e.g., `git tag v2.0.1-markbind.XYZ`
+
+
+
+ The tag used is a lightweight tag. _Don't_ use an annotated tag.
+
+
+1. **Push** everything to the main vue-strap repository (replace `XYZ` with version number).
+
+ ```
+ $ git push upstream master
+ $ git push upstream v2.0.1-markbind.XYZ
+ ```
+
+### Building MarkBind
+
+1. **Navigate to the root** directory for MarkBind
+1. **Update dependencies** by running `npm install`
+1. **If we did a new vue-strap release**:
+
+ Copy `vue-strap.min.js` from the vue-strap repository to the main asset folder, and to each of the test site's `expected/` folder.
+
+ ```sh
+ # copy to main asset folder
+ $ cp /dist/vue-strap.min.js /asset/js/vue-strap.mins.js
+ # for each test site's expected folder:
+ $ cp /dist/vue-strap.min.js /test/functional//expected/markbind/js/vue-strap.min.js
+ ```
+
+ Commit the new vue-strap assets (replace `XYZ` with version number).
+
+ ```sh
+ $ git commit -m 'Update vue-strap version to v2.0.1-markbind.XYZ'
+ ```
+
+
+
+ We uniquely do this for each MarkBind release (rather than spontaneously update the vue-strap files for each affected PR), in order to reduce unnecessary merge conflicts. It also makes it easier for the maintainers to vet the changes.
+
+
+1. **Increment the version number** by running `npm version`. Which to increment (`patch`, `minor` or `major`) depends on what PRs are merged for the new version, which means you must know beforehand about the changes.
+
+ * If there are no significant changes, a `patch` is sufficient: `npm version patch`
+ * If there are significant changes (e.g. breaking changes, new release), a `minor` release is needed:
+ 1. Run `npm version minor` as per normal.
+ 1. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. (Note: You do not have to commit these changes immediately, as we also have to rebuild the test files in the next step anyway.)
+
+ * We rarely do `major` releases, but if necessary, the steps are the same as the `minor` release (just change `minor` to `major`).
+
+1. **Rebuild the test files**.
+ * Unix: `npm run updatetest`
+ * Windows: `npm run updatetestwin`
+
+
+ When rebuilding the expected test files, ensure that **only** the version number is updated. For example, this is correct:
+
+ ```diff
+ diff --git a/test/functional/test_site/expected/bugs/index.html b/test/functional/test_site/expected/bugs/index.html
+ index 779f279..bb3c602 100644
+ --- a/test/functional/test_site/expected/bugs/index.html
+ +++ b/test/functional/test_site/expected/bugs/index.html
+ @@ -4,7 +4,7 @@
+
+
+
+ -
+ +
+
+ Open Bugs
+
+ ```
+
+ However, if there are any extra lines changed, that means that someone screwed up the functional tests, and needs to be fixed accordingly!
+
+1. **Combine** the changes that you made in the last two steps with the version commit generated by `npm version`. To do so, amend the version commit and version tag by doing the following (change `vA.B.C` to the new version's string accordingly).
+
+ ```sh {.no-line-numbers}
+ $ git commit -a --amend --reuse-message vA.B.C
+ $ git tag --force vA.B.C # to reassign the tag to the newly amended commit
+ ```
+
+1. **Push** the new commit and version tag generated by `npm` (change `vA.B.C` to the new version's string accordingly).
+
+ ```sh {.no-line-numbers}
+ $ git push upstream master
+ $ git push upstream vA.B.C
+ ```
+
+1. **Publish** by running `npm publish`. You should receive a notification by `npm` that the publish is successful.
+
+
+1. **Smoke test** the new version by installing the new version (run `npm i -g markbind-cli@A.B.C`) and playing around with it a bit to ensure that it works.
+
+
+
+ If you used `npm link` for your project, ensure that you ==try the new release on another platform== that doesn't use `npm link`, so that we can be sure the end-users can install and use the new version.
+
+
+1. **Verify the website** at markbind.org has been updated.
+
+ The deployment is automated. However, if it doesn't deploy properly for the release, do the following:
+
+ ```sh {.no-line-numbers}
+ $ cd docs
+ $ markbind build -s ug-site.json
+ $ markbind deploy -s ug-site.json
+ ```
+
+1. **Update milestones**. Close the [milestone on GitHub](https://github.com/MarkBind/markbind/milestones) and all issues in that milestone.
+
+ Also create a new milestone for the next iterations. Recommended to have at least two upcoming milestones opened.
+
+1. **Release on GitHub**.
+
+ a. Go to the Markbind release page at https://github.com/MarkBind/markbind/releases.
+
+ b. Click "Draft a new release".
+
+ c. For the tag version, enter `vA.B.C`. (The newly released version should be recognized by GitHub, with an "Existing Tag" indicator, otherwise, ensure that you have pushed the version commit and tag in step 4).
+
+ d. For the release title, leave it blank.
+
+ e. For the main body, use the following template:
+
+ ```markdown
+ # markbind-cli
+
+
+
+
+ ## User Facing Changes
+
+ ### Breaking Changes
+
+
+
+ > Also give a brief explanation note about:
+ > - what was the old feature that was made obsolete
+ > - any replacement feature (if any), and
+ > - how the author should modify his website to migrate from the old feature to the replacement feature (if possible).
+
+ ### Features
+
+
+
+ ### Enhancements
+
+
+
+ ### Fixes
+
+
+
+ ### Documentation
+
+
+
+ ## Other Changes
+
+ ### Code Quality
+
+
+
+ ### DevOps Changes
+
+
+
+ ### Dependencies
+
+
+
+ [MarkBind/vue-strap](https://github.com/MarkBind/vue-strap): v2.0.1-markbind.OLD → v2.0.1-markbind.NEW
+
+ ### Miscellaneous
+
+
+
+ ```
+
+ Use the list of PRs merged in the milestone to write the release notes. You may omit any sections that do not have a single PR under it.
+
+ An example of a release note draft (taken from v1.18.0):
+
+ ```
+ # markbind-cli
+
+ ### Breaking Changes
+
+ #653 Disable decamelize for anchor ID generation (#667, MarkBind/vue-strap#95)
+
+ > Headings with PascalCase wordings now generate a different anchor ID
+ in order to be more compatible with anchor IDs generated by Github
+ Flavored Markdown.
+ >
+ > For example, if we have the following heading:
+ >
+ > ```markdown
+ > # MarkBind docs
+ > ```
+ >
+ > Old anchor id:
+ >
+ > ```
+ > mark-bind-docs
+ > ```
+ >
+ > **New** anchor id:
+ >
+ > ```
+ > markbind-docs
+ > ```
+ >
+
+ ### Features
+
+ #457 Add `deploy -t/--travis` to deploy via Travis (#649)
+ #470 Support custom MarkBind plugins (#474)
+ #642 Support specifying include variables inline (#681)
+
+ ### Enhancements
+
+ #369 Seamless panels: omit caret if not expandable (MarkBind/vue-strap#96)
+ #657 Add temporary styles to prevent FOUC (#664)
+
+ ### Fixes
+
+ #651 Exit MarkBind with non-zero exit code on fatal error (#679)
+
+ ### Documentation
+
+ Restructure user docs on MarkBind syntax (#668)
+ Add documentation for badges (#686)
+ Fix filename capitalization for syntax documentation (#685)
+
+ ### Code Quality
+
+ test: Add diff printing for easier debugging (#632)
+
+ ### Dependencies
+
+ [MarkBind/vue-strap](https://github.com/MarkBind/vue-strap): v2.0.1-markbind.20 → v2.0.1-markbind.21
+ ```
+
+ f. Click "Publish release".
+
+1. **Announce the new release** on our Slack channel (replace `A.B.C` with the new version). Congrats!
+
+ >Published: `npm i -g markbind-cli@A.B.C`
diff --git a/docs/devGuide/settingUp.md b/docs/devGuide/settingUp.md
new file mode 100644
index 0000000000..62bd846378
--- /dev/null
+++ b/docs/devGuide/settingUp.md
@@ -0,0 +1,43 @@
+Setting up
+
+ title: "{{ title }}"
+ layout: devGuide
+
+
+# {{ title }}
+
+
+
+This page explains how to set up your development environment to start contributing to MarkBind.
+
+
+## Prerequisites
+
+1. **Node.js** (LTS or higher) with
+ **npm** v6.12.1 or higher
+1. **Java** 8 or later, and
+ **Graphviz** v2.38 or later
+ %%(The above two are required for one of the third-party library used by MarkBind)%%
+1. **Verify** that all tools are accessible and the versions are as expected by running these commands in the console.
+ * `node --version`
+ * `npm --version`
+ * `java --version`
+ * `dot -V` (for Graphviz)
+
+
+
+We recommend the **WebStorm IDE** for working with MarkBind code.
+
+
+## Setting up the dev environment
+
+1. **Fork and clone** the MarkBind repo.
+1. **Install dependencies** by running `npm install` in the root folder of your cloned repo.
+1. **To bind your cloned version of MarkBind to your console** (instead of the released version of MarkBind), run `npm link` in the root folder of the cloned repo.
+
+
+
+ To go back to the released version of MarkBind, run `npm unlink` followed by `npm i -g markbind-cli`
+
+
+1. **Congrats!** Now you ready to start modifying MarkBind code.
diff --git a/docs/devGuide/styleGuides.md b/docs/devGuide/styleGuides.md
new file mode 100644
index 0000000000..8e2ecd92f3
--- /dev/null
+++ b/docs/devGuide/styleGuides.md
@@ -0,0 +1,20 @@
+Appendix: Style guides
+
+ title: "{{ title }}"
+ layout: devGuide
+ pageNav: default
+
+
+# {{ title }}
+
+
+
+Our coding standards are mostly based on those at [se-education.org/guides](https://se-education.org/guides).
+
+
+Our workflow is mostly based on the guidelines given at se-education.org/guides. This page points to the relevant parts of those guides and provide additional details specific to MarkBind.
+
+
+**To submit a PR**, follow [this guide](https://se-education.org/guides/guidelines/PRs.html), but note the following:
+
+* You can start by looking through [these issues](https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Acomments-desc) marked good first issue. Don't do more than one of them though.
+* As we squash the commits when merging a PR, there is ==no need to follow a strict commit organization or write elaborate commit messages for each commit==.
+* You can refer to the [_Design_](design.html) page to learn about the design and implementation of RepoSense.
+
+The sections below has more information about various stages of submitting a PR.
+
+## Writing code
+
+Use JavaScript ES6 features if possible for better performance, e.g. Promise instead of callback.
+
+Do note [our style guides](styleGuides.html).
+
+## Testing
+
+Our test script does the following:
+
+1. Lints the code for any code and style errors using ESLint.
+1. Builds the test sites whose directory names are listed in `test/functional/test_site`.
+1. For each test site, compares the HTML files generated with the HTML files in its `expected` directory.
+
+#### Running tests
+
+To execute the tests, simply run:
+
+* Unix: `npm run test`
+* Windows: `npm run testwin`
+
+
+#### Updating tests
+
+Whether you are adding a new feature, updating existing features or fixing bugs, make sure to update the test sites to reflect the changes by running this command:
+
+* Unix: `npm run updatetest`
+* Windows: `npm run updatetestwin`
+
+
+ You should always check that the generated output is correct before committing any changes to the test sites.
+
+
+#### Adding test site content
+
+When adding new features, you should also add new site content into an existing test site or create a new test site to demonstrate the new feature. This is to ensure that your feature can be tested by building that test site.
+
+To add a page to an existing test site, for this example, to `test_site`:
+
+1. Add a new test page, e.g., `newTestPage.md`, containing a demonstration of the new feature.
+
+1. Open the `site.json` corresponding to the test site, i.e. `test/functional/test_site/site.json`
+
+1. To include the new page, i.e. `newTestPage.md`, add it to the `pages` array.
+
+ ``` {heading="site.json" highlight-lines="16,17"}
+ "pages": [
+ {
+ "src": "index.md",
+ "title": "Hello World",
+ "frontmatter": {
+ "frontMatterOverrideProperty": "Overridden by front matter override",
+ "globalAndFrontMatterOverrideProperty": "Overridden by front matter override"
+ }
+ },
+ ...
+ {
+ "src": "testLayouts.md",
+ "title": "Hello World"
+ },
+ {,
+ "src": "newTestPage.md",
+ "title": [some title you see fit]
+ },
+ ...
+ ```
+
+1. Update the tests using `npm run updatetest`.
+
+
+
+ When creating a new test site, the directory name of the new test site should be added to `test/functional/test_sites` file.
+
+
+## Linting
+
+We follow [our style guides](styleGuides.html). Using a linter will help check and fix some of the code style errors in your code. It will save time for both you and your code reviewer. The linting tool we use is [ESLint](https://eslint.org/). Here is a [gist](https://gist.github.com/nicholaschuayunzhi/bfe53dbb5f1a0f02d545d55956f9ab7e) with an explanation of the ESLint rules chosen in markbind-cli.
+
+Install developer dependencies (ESLint, related plugins) in your cloned markbind and markbind-cli repositories.
+
+```{.no-line-numbers}
+$ npm install --only=dev
+```
+
+Before making a commit or pull request, you should lint your code by running the following commands from the root of your project:
+
+* To lint a specific file: `./node_modules/.bin/eslint path/to/specificfile.js`
+* To lint all files: `./node_modules/.bin/eslint .`
+
+It is also possible to auto-fix some (not all) style errors:
+* Add the `--fix` flag to correct any fixable style errors
+ e.g., `./node_modules/.bin/eslint . --fix`
+* To correct fixable style errors for both JavaScript and CSS, run `npm run autolint`
+
+
+
+ESLint has [integrations with popular editors](https://eslint.org/docs/user-guide/integrations). They offer features such as "fix errors on save", which will make development smoother.
+
From 19f1279970f698b66cca72f67af5419efb66269b Mon Sep 17 00:00:00 2001
From: damithc <>
Date: Sun, 14 Jun 2020 18:32:49 +0800
Subject: [PATCH 2/3] Update linting instructions as per review
---
docs/devGuide/workflow.md | 11 ++---------
1 file changed, 2 insertions(+), 9 deletions(-)
diff --git a/docs/devGuide/workflow.md b/docs/devGuide/workflow.md
index 31c536882d..082bc3f44a 100644
--- a/docs/devGuide/workflow.md
+++ b/docs/devGuide/workflow.md
@@ -98,20 +98,13 @@ To add a page to an existing test site, for this example, to `test_site`:
We follow [our style guides](styleGuides.html). Using a linter will help check and fix some of the code style errors in your code. It will save time for both you and your code reviewer. The linting tool we use is [ESLint](https://eslint.org/). Here is a [gist](https://gist.github.com/nicholaschuayunzhi/bfe53dbb5f1a0f02d545d55956f9ab7e) with an explanation of the ESLint rules chosen in markbind-cli.
-Install developer dependencies (ESLint, related plugins) in your cloned markbind and markbind-cli repositories.
-
-```{.no-line-numbers}
-$ npm install --only=dev
-```
-
Before making a commit or pull request, you should lint your code by running the following commands from the root of your project:
* To lint a specific file: `./node_modules/.bin/eslint path/to/specificfile.js`
-* To lint all files: `./node_modules/.bin/eslint .`
+* To lint all files: `npm run lint`
It is also possible to auto-fix some (not all) style errors:
-* Add the `--fix` flag to correct any fixable style errors
- e.g., `./node_modules/.bin/eslint . --fix`
+* To correct any fixable style errors, run `npm run lintfix`
* To correct fixable style errors for both JavaScript and CSS, run `npm run autolint`
From 14d9f3626508a59504a488734816df262d4250e1 Mon Sep 17 00:00:00 2001
From: damithc <>
Date: Sun, 14 Jun 2020 21:47:39 +0800
Subject: [PATCH 3/3] Fix copy-paste mistake: RepoSense => MarkBind
---
docs/devGuide/workflow.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/devGuide/workflow.md b/docs/devGuide/workflow.md
index 082bc3f44a..132856ea59 100644
--- a/docs/devGuide/workflow.md
+++ b/docs/devGuide/workflow.md
@@ -16,7 +16,7 @@ Our workflow is mostly based on the guidelines given at se-education.org/guides.
* You can start by looking through [these issues](https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Acomments-desc) marked good first issue. Don't do more than one of them though.
* As we squash the commits when merging a PR, there is ==no need to follow a strict commit organization or write elaborate commit messages for each commit==.
-* You can refer to the [_Design_](design.html) page to learn about the design and implementation of RepoSense.
+* You can refer to the [_Design_](design.html) page to learn about the design and implementation of MarkBind.
The sections below has more information about various stages of submitting a PR.