1 | # DADI API
|
2 |
|
3 | ## Contributing
|
4 |
|
5 | We'd love for you to contribute to our source code and to make DADI API even better.
|
6 |
|
7 | Here are the guidelines we'd like you to follow:
|
8 |
|
9 | - [Question or Problem?](#question)
|
10 | - [Issues and Bugs](#issue)
|
11 | - [Feature Requests](#feature)
|
12 | - [Submission Guidelines](#submit)
|
13 | - [Coding Rules](#rules)
|
14 | - [Git Commit Guidelines](#commit)
|
15 |
|
16 | ## <a name="question"></a> Got a Question or Problem?
|
17 |
|
18 | Documentation can be found at the [docs.dadi.tech](https://docs.dadi.tech/api) site.
|
19 |
|
20 | If the documentation doesn't answer your problem please feel free to email the
|
21 | DADI team directly on: team@dadi.tech, or join us on [Slack](http://dadi-chat.herokuapp.com).
|
22 |
|
23 | ## <a name="issue"></a> Found an Issue?
|
24 | If you find a bug in the source code or a mistake in the documentation, you can help us by
|
25 | submitting an issue to our [GitHub Repository][github]. But we'd love it if you
|
26 | submitted a Pull Request with a fix instead!
|
27 |
|
28 | **Please see the Submission Guidelines below**.
|
29 |
|
30 | ## <a name="feature"></a> Want a Feature?
|
31 | You can request a new feature by submitting an issue to our [GitHub][issues] issue tracker.
|
32 | If you would like to implement a new feature then consider what kind of change it is:
|
33 |
|
34 | * **Major Changes** that you wish to contribute to the project should be added as
|
35 | a Feature Request in the [GitHub][issues] issue tracker. This will get the conversation
|
36 | started.
|
37 | * **Small Changes** can be crafted and submitted to the [GitHub Repository][github] as a Pull Request.
|
38 |
|
39 | ## <a name="submit"></a> Submission Guidelines
|
40 |
|
41 | ### Submitting an Issue
|
42 | Before you submit your issue [search the archive][issues], maybe your question was already answered.
|
43 |
|
44 | If your issue appears to be a bug, and hasn't been reported, open a new issue.
|
45 | Help us to maximize the effort we can spend fixing issues and adding new
|
46 | features, by not reporting duplicate issues. Providing the following information will increase the
|
47 | chances of your issue being dealt with quickly:
|
48 |
|
49 | * **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
|
50 | * **Motivation for or Use Case** - explain why this is a bug for you
|
51 | * **DADI API Version**
|
52 | * **Operating System**
|
53 | * **Steps to Reproduce** - provide a set of steps to follow to reproduce the error.
|
54 | * **Related Issues** - has a similar issue been reported before?
|
55 | * **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
|
56 | causing the problem (e.g. a line of code or a commit)
|
57 |
|
58 | ### Submitting a Pull Request
|
59 | Before you submit your pull request consider the following guidelines:
|
60 |
|
61 | * Search [GitHub][pulls] for an open or closed Pull Request
|
62 | that relates to your submission. You don't want to duplicate effort.
|
63 | * Fork the original repository and clone your fork ([see this GitHub article](https://help.github.com/articles/fork-a-repo/)).
|
64 | * Add the original repository as an upstream remote: `git remote add upstream https://github.com/dadi/api.git`
|
65 |
|
66 | * Make your changes in a new git branch. Name your branch using the format `topic/branch_name`.
|
67 | Use `fix` for fixes and `feature` for features:
|
68 |
|
69 | ```shell
|
70 | git checkout -b fix/my-fix-branch master
|
71 | ```
|
72 | ```shell
|
73 | git checkout -b feature/my-new-feature-branch master
|
74 | ```
|
75 |
|
76 | * Create your patch, **including appropriate test cases**.
|
77 | * Follow our [Coding Rules](#rules).
|
78 | * Run the full test suite using `npm test` and ensure that all tests pass.
|
79 | * Commit your changes using a descriptive commit message that follows our
|
80 | [commit message conventions](#commit-message-format) and passes our commit message presubmit hook. Adherence to the [commit message conventions](#commit-message-format) is required because release notes are automatically generated from these messages.
|
81 | * Push your branch to GitHub:
|
82 |
|
83 | ```shell
|
84 | git push origin fix/my-fix-branch
|
85 | ```
|
86 |
|
87 | * In GitHub, send a pull request to `dadi/api:master`.
|
88 | * If we suggest changes then:
|
89 | * Make the required updates.
|
90 | * Re-run the full test suite to ensure tests are still passing.
|
91 | * Commit your changes to your branch (e.g. `fix/my-fix-branch`).
|
92 | * Push the changes to GitHub (this will update your Pull Request).
|
93 |
|
94 | If the pull request gets too outdated we may ask you to rebase and force push to update the pull request:
|
95 |
|
96 | ```shell
|
97 | git rebase master -i
|
98 | git push origin fix/my-fix-branch -f
|
99 | ```
|
100 |
|
101 | *WARNING. Squashing or reverting commits and forced push thereafter may remove GitHub comments on code that were previously made by you and others in your commits.*
|
102 |
|
103 | * Documentation! Please add relevant documentation to the pull request. If this is a new feature then
|
104 | please document it fully within the pull request. If you're making changes to an existing feature, please
|
105 | give us a link to the existing [documentation][docs] along with your documentation changes. If you need
|
106 | an example of excellent pull request documentation, have a look at the [effort put in here](https://github.com/dadi/api/pull/27).
|
107 |
|
108 | > That's it! Thank you for your contribution!
|
109 |
|
110 | #### After your pull request is merged
|
111 |
|
112 | After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:
|
113 |
|
114 | * Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
|
115 |
|
116 | ```shell
|
117 | git push origin --delete my-fix-branch
|
118 | ```
|
119 |
|
120 | * Check out the master branch:
|
121 |
|
122 | ```shell
|
123 | git checkout master -f
|
124 | ```
|
125 |
|
126 | * Delete the local branch:
|
127 |
|
128 | ```shell
|
129 | git branch -D my-fix-branch
|
130 | ```
|
131 |
|
132 | * Update your master with the latest upstream version:
|
133 |
|
134 | ```shell
|
135 | git pull --ff upstream master
|
136 | ```
|
137 |
|
138 | ## <a name="rules"></a> Coding Rules
|
139 | To ensure consistency throughout the source code, keep these rules in mind as you are working:
|
140 |
|
141 | * Please use **two-space indentation**, as used in Node.JS itself.
|
142 | * All features or bug fixes **must be tested** by one or more tests. Browse the [test
|
143 | suite][tests] for examples.
|
144 | * All public API methods **must be documented** with [JSDoc](http://usejsdoc.org/).
|
145 |
|
146 | ## <a name="commit"></a> Git Commit Guidelines
|
147 |
|
148 | ### One Change Per Commit
|
149 |
|
150 | A commit should contain exactly one logical change. A logical change includes adding a new feature, fixing a specific bug, etc. If it's not possible to describe the high level change in a few words, it is most likely too complex for a single commit. The diff itself should be as concise as reasonably possibly and it's almost always better to err on the side of too many patches than too few. As a rule of thumb, given only the commit message, another developer should be able to implement the same patch in a reasonable amount of time.
|
151 |
|
152 | Please don't include more than one change in each patch. If your commit message requires an "and" in the middle, it's likely you need separate commits.
|
153 |
|
154 | ### Commit Message Format
|
155 |
|
156 | We have very precise rules over how our git commit messages can be formatted. This leads to **more readable messages** that are easy to follow when looking through the **project history**. We also use the git commit messages to **generate the change log**.
|
157 |
|
158 | We use [husky](https://www.npmjs.com/package/husky) and [validate-commit-msg](https://github.com/kentcdodds/validate-commit-msg) to perform the commit message validation. Commit messages will be validated when you commit. When validation fails, you'll see a message similar to the following:
|
159 |
|
160 | ```bash
|
161 | > husky - npm run -s commitmsg
|
162 |
|
163 | INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" !
|
164 | ```
|
165 |
|
166 | #### Line Length
|
167 |
|
168 | Any line of the commit message cannot be longer 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.
|
169 |
|
170 | #### Message Format
|
171 |
|
172 | Each commit message consists of a **header**, a **body** and a **footer**. The header has a special format that includes a **type** and a **subject**:
|
173 |
|
174 | ```
|
175 | type: subject
|
176 |
|
177 | Optional long description
|
178 |
|
179 | Fix #xxx
|
180 | Close #yyy
|
181 | Ref #zzz
|
182 | ```
|
183 |
|
184 | * Use `Fix #xxx` when the commit fixes an open issue.
|
185 | * Use `Close #xxx` when the commit closes an open pull request.
|
186 | * Use `Ref #xxx` when referencing an issue or pull request that is already closed or should remain open. Examples include partial fixes and commits that add a test but not a fix.
|
187 |
|
188 | ### Reverting
|
189 | If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
|
190 |
|
191 | ### Type
|
192 | Must be one of the following:
|
193 |
|
194 | * **feat**: A new feature
|
195 | * **fix**: A bug fix
|
196 | * **docs**: Documentation only changes
|
197 | * **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
|
198 | * **refactor**: A code change that neither fixes a bug nor adds a feature
|
199 | * **perf**: A code change that improves performance
|
200 | * **test**: Adding missing tests
|
201 | * **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
|
202 |
|
203 | ### Subject
|
204 | The subject contains a succinct description of the change:
|
205 |
|
206 | * use the imperative, present tense: "fix" not "fixed" nor "fixes"
|
207 | * don't capitalize first letter
|
208 | * no dot (.) at the end
|
209 |
|
210 | ### Body
|
211 | Just as in the **subject**, write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug". This convention matches up with commit messages generated by commands like `git merge` and `git revert`.
|
212 |
|
213 | The body should include the motivation for the change and contrast this with previous behavior.
|
214 |
|
215 | ### Footer
|
216 | The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
|
217 |
|
218 | **Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
|
219 |
|
220 |
|
221 | [github]: https://github.com/dadi/api
|
222 | [issues]: https://github.com/dadi/api/issues
|
223 | [pulls]: https://github.com/dadi/api/pulls
|
224 | [tests]: https://github.com/dadi/api/tree/master/test
|