|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We encourage any form of contribution, whether that be issues, comments, or pull requests. If you are going to be submitting a PR, there are a few things we would appreciate that you do to keep the codebase clean: |
| 4 | + |
| 5 | +* **Write tests.** We try as close to 100% code coverage as possible on this repo so any new code that gets written should have accompanying tests. |
| 6 | +* **Follow the linter.** We use our [ESLint configuration with Airbnb JavaScript Styleguide](https://github.com/airbnb/javascript), and we run `npm run lint` in our Travis builds. |
| 7 | +* **Ask questions if you aren't sure.** If you have any questions while implementing a fix or feature, feel free to create an issue and ask us. We're happy to help! |
| 8 | + |
| 9 | +## <a name="submit"></a> Submission Guidelines |
| 10 | + |
| 11 | +### <a name="submit-issue"></a> Submitting an Issue |
| 12 | + |
| 13 | +Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available. |
| 14 | + |
| 15 | +### <a name="submit-pr"></a> Submitting a Pull Request (PR) |
| 16 | +Before you submit your Pull Request (PR) consider the following guidelines: |
| 17 | + |
| 18 | +1. Search [GitHub](https://github.com/amejiarosario/dsa.js/pulls) for an open or closed PR |
| 19 | + that relates to your submission. You don't want to duplicate effort. |
| 20 | +1. Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add. |
| 21 | + Discussing the design up front helps to ensure that we're ready to accept your work. |
| 22 | +1. Fork the `amejiarosario/dsa.js` repo. |
| 23 | +1. Make your changes in a new git branch: |
| 24 | + |
| 25 | + ```shell |
| 26 | + git checkout -b my-fix-branch master |
| 27 | + ``` |
| 28 | + |
| 29 | +1. Create your patch, **including appropriate test cases**. |
| 30 | +1. Run the full test suite, and ensure that all tests pass. |
| 31 | +1. Commit your changes using a descriptive commit message that follows our |
| 32 | + [commit message conventions](#commit). Adherence to these conventions |
| 33 | + is necessary because release notes are automatically generated from these messages. |
| 34 | + |
| 35 | + ```shell |
| 36 | + git commit -a |
| 37 | + ``` |
| 38 | + |
| 39 | + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. |
| 40 | + |
| 41 | +1. Push your branch to GitHub: |
| 42 | + |
| 43 | + ```shell |
| 44 | + git push origin my-fix-branch |
| 45 | + ``` |
| 46 | + |
| 47 | +1. In GitHub, send a pull request to `dsa.js:master`. |
| 48 | +* If we suggest changes then: |
| 49 | + * Make the required updates. |
| 50 | + * Re-run the test suites to ensure tests are still passing. |
| 51 | + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): |
| 52 | + |
| 53 | + ```shell |
| 54 | + git rebase master -i |
| 55 | + git push -f |
| 56 | + ``` |
| 57 | + |
| 58 | +That's it! Thank you for your contribution! |
| 59 | + |
| 60 | +#### After your pull request is merged |
| 61 | + |
| 62 | +After your pull request is merged, you can safely delete your branch and pull the changes |
| 63 | +from the main (upstream) repository: |
| 64 | + |
| 65 | +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: |
| 66 | + |
| 67 | + ```shell |
| 68 | + git push origin --delete my-fix-branch |
| 69 | + ``` |
| 70 | + |
| 71 | +* Check out the master branch: |
| 72 | + |
| 73 | + ```shell |
| 74 | + git checkout master -f |
| 75 | + ``` |
| 76 | + |
| 77 | +* Delete the local branch: |
| 78 | + |
| 79 | + ```shell |
| 80 | + git branch -D my-fix-branch |
| 81 | + ``` |
| 82 | + |
| 83 | +* Update your master with the latest upstream version: |
| 84 | + |
| 85 | + ```shell |
| 86 | + git pull --ff upstream master |
| 87 | + ``` |
| 88 | + |
| 89 | +## <a name="commit"></a> Commit Message Guidelines |
| 90 | + |
| 91 | +We have some guidelines how our git commit messages can be formatted. This leads to **more |
| 92 | +readable messages** that are easy to follow when looking through the **project history**. But also, |
| 93 | +we use the git commit messages to **generate the change log**. |
| 94 | + |
| 95 | +### Commit Message Format |
| 96 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 97 | +format that includes a **type**, a **scope** and a **subject**: |
| 98 | + |
| 99 | +``` |
| 100 | +<type>(<scope>): <subject> |
| 101 | +<BLANK LINE> |
| 102 | +<body> |
| 103 | +<BLANK LINE> |
| 104 | +<footer> |
| 105 | +``` |
| 106 | + |
| 107 | +The **header** is mandatory and the **scope** of the header is optional. |
| 108 | + |
| 109 | +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier |
| 110 | +to read on GitHub as well as in various git tools. |
| 111 | + |
| 112 | +The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any. |
| 113 | + |
| 114 | +``` |
| 115 | +docs(changelog): update changelog to beta.5 |
| 116 | +``` |
| 117 | + |
| 118 | +``` |
| 119 | +fix(release): need to depend on latest rxjs and zone.js |
| 120 | + |
| 121 | +The version in our package.json gets copied to the one we publish, and users need the latest of these. |
| 122 | +``` |
| 123 | + |
| 124 | +### Revert |
| 125 | +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. |
| 126 | + |
| 127 | +### Type |
| 128 | +Must be one of the following: |
| 129 | + |
| 130 | +* **break**: Breaking changes. Remove functionality or change API. Breaks backward compatibility |
| 131 | +* **feat**: A new feature |
| 132 | +* **fix**: A bug fix |
| 133 | +* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
| 134 | +* **ci**: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs) |
| 135 | +* **docs**: Documentation only changes |
| 136 | +* **perf**: A code change that improves performance |
| 137 | +* **refactor**: A code change that neither fixes a bug nor adds a feature |
| 138 | +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
| 139 | +* **test**: Adding missing tests or correcting existing tests |
| 140 | + |
| 141 | +### Scope |
| 142 | +The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages. |
| 143 | + |
| 144 | +The following is an example of supported scopes: |
| 145 | + |
| 146 | +* **list** |
| 147 | +* **map** |
| 148 | +* **tree** |
| 149 | +* **graph** |
| 150 | +* **sorting** |
| 151 | +* etc. |
| 152 | + |
| 153 | +### Subject |
| 154 | +The subject contains a succinct description of the change: |
| 155 | + |
| 156 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 157 | +* don't capitalize the first letter |
| 158 | +* no dot (.) at the end |
| 159 | + |
| 160 | +### Body |
| 161 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 162 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 163 | + |
| 164 | +### Footer |
| 165 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 166 | +reference GitHub issues that this commit **Closes**. |
| 167 | + |
| 168 | +``` |
| 169 | +Closes #234 |
| 170 | +``` |
| 171 | + |
| 172 | +**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. |
| 173 | + |
| 174 | + |
| 175 | +## Generating Changelog |
| 176 | + |
| 177 | +We use these three sections in changelog: new features, bug fixes, breaking changes. |
| 178 | + |
| 179 | +List of all subjects (first lines in commit message) since last release: |
| 180 | + |
| 181 | +```sh |
| 182 | +git log <last tag> HEAD --pretty=format:%s |
| 183 | + |
| 184 | +# example |
| 185 | +git log 1.1.0..HEAD --pretty=format:%s |
| 186 | +``` |
| 187 | + |
| 188 | +New features in this release |
| 189 | + |
| 190 | +```sh |
| 191 | +git log <last release> HEAD --grep feat |
| 192 | + |
| 193 | +# example |
| 194 | +git log 6.0.0..HEAD --pretty=format:%s | grep feat |
| 195 | +# |
| 196 | +git log 6.0.0..HEAD --pretty=format:"- %s [commit](https://github.com/amejiarosario/dsa.js/commit/%H)" | grep feat |
| 197 | +``` |
0 commit comments