1 | # Developing Markdown-Editor
|
2 |
|
3 | * [Development Setup][developers.setup]
|
4 | * [Coding Rules][developers.rules]
|
5 | * [Commit Message Guidelines][developers.commits]
|
6 | * [Writing Documentation][developers.documentation]
|
7 |
|
8 | ## <a name="setup"> Development Setup
|
9 |
|
10 | This document describes how to set up your development environment to build and test Markdown-Editor, and
|
11 | explains the basic mechanics of using `git`, `node`, `npm`.
|
12 |
|
13 | ### Installing Dependencies
|
14 |
|
15 | Before you can build Markdown-Editor, you must install and configure the following dependencies on your
|
16 | machine:
|
17 |
|
18 | * [Git][git]: The [Github Guide to Installing Git][git-setup] is a good source of information.
|
19 |
|
20 | * [Node.js v10.16.0 'Dubnium' (LTS)][node]: We use Node to generate the documentation, run a
|
21 | development web server, run tests, and generate distributable files. Depending on your system,
|
22 | you can install Node either from source or as a pre-packaged bundle.
|
23 |
|
24 | We recommend using [nvm][nvm] (or [nvm-windows][nvm-windows])
|
25 | to manage and install Node.js, which makes it easy to change the version of Node.js per project.
|
26 |
|
27 | ### Forking Markdown-Editor on Github
|
28 |
|
29 | To contribute code to Markdown-Editor, you must have a GitHub account so you can push code to your own
|
30 | fork of Markdown-Editor and open Pull Requests in the [GitHub Repository][github].
|
31 |
|
32 | To create a Github account, follow the instructions [here][github-signup].
|
33 | Afterwards, go ahead and [fork][github-forking] the
|
34 | [main Markdown-Editor repository][github].
|
35 |
|
36 | ### Building Markdown-Editor
|
37 |
|
38 | To build Markdown-Editor, you clone the source code repository and use lerna to build:
|
39 |
|
40 | ```shell
|
41 | # Clone your Github repository:
|
42 | git clone https://github.com/<github username>/markdown-editor.git
|
43 |
|
44 | # Go to the Markdown-Editor directory:
|
45 | cd markdown-editor
|
46 |
|
47 | # Add the main Markdown-Editor repository as an upstream remote to your repository:
|
48 | git remote add upstream "https://github.com/accordproject/markdown-editor.git"
|
49 |
|
50 | # Install node.js dependencies:
|
51 | npm install
|
52 | ```
|
53 |
|
54 | ### Keeping In Sync
|
55 |
|
56 | It is good practice to always keep your `origin/master` in sync with `upstream/master`. You don’t have to, but it makes your life easier. Do your work in branches of your fork, and periodically sync up your `master` with the `master` of `upstream` as follows. You should definitely do this before creating a pull request.
|
57 |
|
58 | ```shell
|
59 | git fetch --all --prune
|
60 | git checkout master
|
61 | git merge --ff-only upstream/master
|
62 | git push origin master
|
63 | ```
|
64 |
|
65 | ### <a name="unit-tests"></a> Running the Unit Test Suite
|
66 |
|
67 | We write unit and integration tests with Enzyme and execute them with Jest. To run all of the
|
68 | tests once on Chrome run:
|
69 |
|
70 | ```shell
|
71 | npm run test
|
72 | ```
|
73 |
|
74 | ## <a name="rules"></a> Coding Rules
|
75 |
|
76 | To ensure consistency throughout the source code, keep these rules in mind as you are working:
|
77 |
|
78 | * All features or bug fixes **must be tested** by one or more [specs][developers.unit-tests].
|
79 | * All public API methods **must be documented** with jsdoc. To see how we document our APIs, please check
|
80 | out the existing source code and see the section about [writing documentation][developers.documentation]
|
81 | * With the exceptions listed below, we follow the rules contained in
|
82 | [Google's JavaScript Style Guide][google].
|
83 |
|
84 | ## <a name="commits"></a> Git Commit Guidelines
|
85 |
|
86 | We have very precise rules over how our git commit messages can be formatted. This leads to **more
|
87 | readable messages** that are easy to follow when looking through the **project history** and **git logs**.
|
88 | But also, we use the git commit messages to **generate the Markdown-Editor change log**.
|
89 |
|
90 | The commit message formatting can be added using a version of typical git workflow.
|
91 |
|
92 | ### Commit Message Format
|
93 | Each commit message consists of a mandatory **type**, **scope**, **subject**, and **footer**. This is a specific format:
|
94 |
|
95 | ```shell
|
96 | <type>(<scope>): <subject> - <footer>
|
97 | ```
|
98 |
|
99 | This allows the message to be easier to read on GitHub as well as in various git tools.
|
100 |
|
101 | ### Revert
|
102 | If the commit reverts a previous commit, it should begin with `revert: `, followed by the subject, where it
|
103 | should say: `this reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
|
104 | A commit with this format is automatically created by the [`git revert`][git-revert] command.
|
105 |
|
106 | ### Type
|
107 | Must be one of the following:
|
108 |
|
109 | * **`feat`**: A new feature
|
110 | * **`fix`**: A bug fix
|
111 | * **`docs`**: Documentation only changes
|
112 | * **`style`**: Changes that do not affect the meaning of the code (white-space, formatting, missing
|
113 | semi-colons, etc)
|
114 | * **`refactor`**: A code change that neither fixes a bug nor adds a feature
|
115 | * **`perf`**: A code change that improves performance
|
116 | * **`test`**: Adding missing or correcting existing tests
|
117 | * **`chore`**: Changes to the build process or auxiliary tools and libraries such as documentation
|
118 | generation
|
119 |
|
120 | ### Scope
|
121 | The scope will be specifying the place of the commit change; the focal point of new code or best
|
122 | description for where changes can be found.
|
123 |
|
124 | You can use `*` when the change affects more than a single scope.
|
125 |
|
126 | ### Subject
|
127 | The subject contains succinct description of the change:
|
128 |
|
129 | * use the imperative, present tense: "change" not "changed" nor "changes"
|
130 | * don't capitalize first letter
|
131 | * kept under 50 characters
|
132 | * no dot (.) at the end
|
133 |
|
134 | ### Footer
|
135 | The footer should contain [reference GitHub Issues][github-issues] that this commit addresses.
|
136 |
|
137 | ## <a name="pullrequests"></a> GitHub Pull Request Guidelines
|
138 | Pull Requests should consist of a complete addition to the code which contains value.
|
139 | Because the commits inside follow a pattern, the title should be an extension or summary of all the commits inside.
|
140 |
|
141 | Pull Request titles should follow [commit message formatting][developers.commits].
|
142 |
|
143 | Formatting for the body is displayed in this example:
|
144 |
|
145 | ```shell
|
146 | # Issue #20
|
147 |
|
148 | ### Changes
|
149 | - Change one
|
150 | - Subchange one
|
151 | - Subchange two
|
152 | - Change two
|
153 | - Theoretically this should be listing all the commit messages included in this PR
|
154 |
|
155 | ### Flags
|
156 | - Possible issues or holds for reviewers to note
|
157 | - List any breaking changes here.
|
158 |
|
159 | ### Related Issues
|
160 | - Link any issues or pull requests relating to this
|
161 | ```
|
162 |
|
163 | When approved and ready to merge, a Pull Request should be squashed down to a single buildable commit and merged into master.
|
164 |
|
165 | ## <a name="documentation"></a> Writing Documentation
|
166 |
|
167 | The Markdown-Editor project uses [jsdoc][jsdoc] for all of its code
|
168 | documentation.
|
169 |
|
170 | This means that all the docs are stored inline in the source code and so are kept in sync as it
|
171 | changes.
|
172 |
|
173 | This means that since we generate the documentation from the source code, we can easily provide
|
174 | version-specific documentation by simply checking out a version of Markdown-Editor and running the build.
|
175 |
|
176 | ## License <a name="license"></a>
|
177 |
|
178 | Accord Project source code files are made available under the [Apache License, Version 2.0][apache].
|
179 |
|
180 | Accord Project documentation files are made available under the [Creative Commons Attribution 4.0 International License][creativecommons] (CC-BY-4.0).
|
181 |
|
182 | [developers.setup]: DEVELOPERS.md#setup
|
183 | [developers.rules]: DEVELOPERS.md#rules
|
184 | [developers.commits]: DEVELOPERS.md#commits
|
185 | [developers.documentation]: DEVELOPERS.md#documentation
|
186 | [developers.unit-tests]: DEVELOPERS.md#unit-tests
|
187 |
|
188 | [git]: http://git-scm.com/
|
189 | [git-setup]: https://help.github.com/en/articles/set-up-git
|
190 | [node]: https://nodejs.org/en/
|
191 | [nvm]: https://github.com/creationix/nvm
|
192 | [nvm-windows]: https://github.com/coreybutler/nvm-windows
|
193 | [github]: https://github.com/accordproject/markdown-editor
|
194 | [github-signup]: https://github.com/signup/free
|
195 | [github-issues]: https://github.com/accordproject/markdown-editor/issues
|
196 | [github-forking]: http://help.github.com/forking
|
197 | [google]: https://google.github.io/styleguide/jsguide.html
|
198 | [commit]: https://github.com/commitizen/cz-cli
|
199 | [jsdoc]: http://usejsdoc.org/
|
200 |
|
201 | [apache]: https://github.com/accordproject/markdown-editor/blob/master/LICENSE
|
202 | [creativecommons]: http://creativecommons.org/licenses/by/4.0/ |
\ | No newline at end of file |