|
| 1 | +We are excited to have you working on the project and coordially request that you follow the Guidelines: |
| 2 | + |
| 3 | + - [Code Style Guidelines](#rules) |
| 4 | + - [Commit Message Guidelines](#commit) |
| 5 | + |
| 6 | +## <a name="rules"></a> Coding Rules |
| 7 | +To ensure consistency throughout the source code, keep these rules in mind as you are working: |
| 8 | + |
| 9 | +* All features or bug fixes **must pass all tests** (run `gulp` to jshint, build and test). |
| 10 | +* All public API methods **must be documented** with ngdoc, an extended version of jsdoc (we added |
| 11 | + support for markdown and templating via @ngdoc tag). To see how we document our APIs, please check |
| 12 | + out the existing ngdocs and see [this wiki page][ngDocs]. |
| 13 | + |
| 14 | +## <a name="commit"></a> Git Commit Guidelines |
| 15 | + |
| 16 | +We have very precise rules over how our git commit messages can be formatted for maintenance of the changelog and semvar versioning. This leads to **more |
| 17 | +readable messages** that are easy to follow when looking through the **project history**. But also, |
| 18 | +we use the git commit messages to **generate the change log**. |
| 19 | + |
| 20 | + |
| 21 | +## Recommended workflow |
| 22 | + |
| 23 | +1. Make changes |
| 24 | +2. Run `gulp` or `gulp test` to run Karma tests. |
| 25 | +3. If tests pass, commit those changes using the conventions below. |
| 26 | +4. Run `gulp bump` to update the version in package.json, add a git tag and generate the updated CHANGELOG.md. |
| 27 | +5. `conventionalChangelog` (see https://github.com/ajoslin/conventional-changelog) |
| 28 | +6. Commit updated `package.json` and `CHANGELOG.md` files |
| 29 | +7. Push |
| 30 | +8. Create PR |
| 31 | + |
| 32 | +The reason why you should commit and tag after `conventionalChangelog` is that the CHANGELOG should be included in the new release, hence `gitRawCommitsOpts.from` defaults to the latest semver tag. |
| 33 | + |
| 34 | +This process is automated with gulp, including determining the type of version to bump (major, minor or patch). To use Gulp, follow these steps: |
| 35 | + |
| 36 | +1. Complete a feature or bug |
| 37 | +2. Commit the changes |
| 38 | +3. Run `gulp bump` (this will bump the version in package.json, run conventional-changelog to update the changelog and tag the version. |
| 39 | +4. Push |
| 40 | + |
| 41 | +### Commit Message Format |
| 42 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 43 | +format that includes a **type**, a **scope** and a **subject**: |
| 44 | + |
| 45 | +``` |
| 46 | +<type>(<scope>): <subject> |
| 47 | +<BLANK LINE> |
| 48 | +<body> |
| 49 | +<BLANK LINE> |
| 50 | +<footer> |
| 51 | +``` |
| 52 | + |
| 53 | +The **header** is mandatory and the **scope** of the header is optional. |
| 54 | + |
| 55 | +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier |
| 56 | +to read on GitHub as well as in various git tools. |
| 57 | + |
| 58 | +### Revert |
| 59 | +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. |
| 60 | + |
| 61 | +### Type |
| 62 | +Must be one of the following: |
| 63 | + |
| 64 | +* **feat**: A new feature |
| 65 | +* **fix**: A bug fix |
| 66 | +* **docs**: Documentation only changes |
| 67 | +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing |
| 68 | + semi-colons, etc) |
| 69 | +* **refactor**: A code change that neither fixes a bug nor adds a feature |
| 70 | +* **perf**: A code change that improves performance |
| 71 | +* **test**: Adding missing tests |
| 72 | +* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation |
| 73 | + generation |
| 74 | + |
| 75 | +### Scope |
| 76 | +The scope could be anything specifying place of the commit change. For example `$location`, |
| 77 | +`$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`, `ngView`, etc... |
| 78 | + |
| 79 | +### Subject |
| 80 | +The subject contains succinct description of the change: |
| 81 | + |
| 82 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 83 | +* don't capitalize first letter |
| 84 | +* no dot (.) at the end |
| 85 | + |
| 86 | +### Body |
| 87 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 88 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 89 | + |
| 90 | +### Footer |
| 91 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 92 | +reference github issues that this commit **Closes**. |
| 93 | + |
| 94 | +**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. |
| 95 | + |
| 96 | +#### Examples |
| 97 | + |
| 98 | +Appears under "Features" header, pencil subheader: |
| 99 | + |
| 100 | +``` |
| 101 | +feat(pencil): add 'graphiteWidth' option |
| 102 | +``` |
| 103 | + |
| 104 | +Appears under "Bug Fixes" header, graphite subheader, with a link to issue #GSNP-28: |
| 105 | + |
| 106 | +``` |
| 107 | +fix(graphite): stop graphite breaking when width < 0.1 |
| 108 | +
|
| 109 | +Closes #123 |
| 110 | +``` |
| 111 | + |
| 112 | +Appears under "Performance Improvements" header, and under "Breaking Changes" with the breaking change explanation: |
| 113 | + |
| 114 | +``` |
| 115 | +perf(pencil): remove graphiteWidth option |
| 116 | +
|
| 117 | +BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reason. |
| 118 | +``` |
| 119 | + |
| 120 | +The following commit and commit `667ecc1` do not appear in the changelog if they are under the same release. If not, the revert commit appears under the "Reverts" header. |
| 121 | + |
| 122 | +``` |
| 123 | +revert: feat(pencil): add 'graphiteWidth' option |
| 124 | +
|
| 125 | +This reverts commit 667ecc1654a317a13331b17617d973392f415f02. |
| 126 | +``` |
| 127 | + |
| 128 | +A detailed explanation can be found in this [document][https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#]. |
0 commit comments