|
| 1 | +# Contributing to RxJS Docs |
| 2 | + |
| 3 | +[Read and abide by the Code of Conduct](CODE_OF_CONDUCT.md)! Even if you don't read it, |
| 4 | +it still applies to you. Ignorance is not an exemption. |
| 5 | + |
| 6 | +Contents |
| 7 | + |
| 8 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 9 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 10 | + |
| 11 | +- [Submitting a Pull Request (PR)](#submitting-a-pull-request-pr) |
| 12 | + - [After your pull request is merged](#after-your-pull-request-is-merged) |
| 13 | +- [Commit Message Guidelines](#commit-message-guidelines) |
| 14 | + - [Commit Message Format](#commit-message-format) |
| 15 | + - [Revert](#revert) |
| 16 | + - [Type](#type) |
| 17 | + - [Scope](#scope) |
| 18 | + - [Subject](#subject) |
| 19 | + - [Body](#body) |
| 20 | + - [Footer](#footer) |
| 21 | + |
| 22 | + <!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 23 | + |
| 24 | +(This document is a work and progress and is subject to change) |
| 25 | + |
| 26 | +## Building/Testing |
| 27 | + |
| 28 | +The build and test structure is fairly primitive at the moment. There are various npm scripts that can be run: |
| 29 | + |
| 30 | +- start: runs the dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files. |
| 31 | +- test: runs tests with `jasmine`, must have built prior to running. |
| 32 | +- build: build artifacts will be stored in the `dist/` directory |
| 33 | +- build-prod: builds for production using the `--prod` flag |
| 34 | +- commit: runs git commit wizard for passing rxjs-github-bot message validator |
| 35 | + |
| 36 | +## Submitting a Pull Request (PR) |
| 37 | +Before you submit your Pull Request (PR) consider the following guidelines: |
| 38 | + |
| 39 | +* Search [GitHub](https://github.com/ReactiveX/rxjs-docs/pulls) for an open or closed PR |
| 40 | + that relates to your submission. You don't want to duplicate effort. |
| 41 | +* Make your changes in a new git branch: |
| 42 | + |
| 43 | + ```shell |
| 44 | + git checkout -b my-fix-branch master |
| 45 | + ``` |
| 46 | + |
| 47 | +* Create your patch, following [code style guidelines](#coding-style-guidelines), and **including appropriate test cases**. |
| 48 | +* Run the full test suite and ensure that all tests pass. |
| 49 | +* Run the micro and macro performance tests against your feature branch and compare against master |
| 50 | + to ensure performance wasn't changed for the worse. |
| 51 | +* Commit your changes using a descriptive commit message that follows our |
| 52 | + [commit message guidelines](#commit-message-guidelines). Adherence to these conventions |
| 53 | + is necessary because release notes are automatically generated from these messages. |
| 54 | +
|
| 55 | + ```shell |
| 56 | + git add . |
| 57 | + npm run commit |
| 58 | + ``` |
| 59 | + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. |
| 60 | +
|
| 61 | +* Push your branch to GitHub: |
| 62 | +
|
| 63 | + ```shell |
| 64 | + git push origin my-fix-branch |
| 65 | + ``` |
| 66 | +
|
| 67 | +* In GitHub, send a pull request to `rxjs-docs:master`. |
| 68 | +* If we suggest changes then: |
| 69 | + * Make the required updates. |
| 70 | + * Re-run the test suites to ensure tests are still passing. |
| 71 | + * Re-run performance tests to make sure your changes didn't hurt performance. |
| 72 | + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): |
| 73 | + |
| 74 | + ```shell |
| 75 | + git rebase master -i |
| 76 | + git push -f |
| 77 | + ``` |
| 78 | + |
| 79 | +That's it! Thank you for your contribution! |
| 80 | +
|
| 81 | +
|
| 82 | +### After your pull request is merged |
| 83 | +
|
| 84 | +After your pull request is merged, you can safely delete your branch and pull the changes |
| 85 | +from the main (upstream) repository: |
| 86 | +
|
| 87 | +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: |
| 88 | +
|
| 89 | + ```shell |
| 90 | + git push origin --delete my-fix-branch |
| 91 | + ``` |
| 92 | +
|
| 93 | +* Check out the master branch: |
| 94 | +
|
| 95 | + ```shell |
| 96 | + git checkout master -f |
| 97 | + ``` |
| 98 | +
|
| 99 | +* Delete the local branch: |
| 100 | +
|
| 101 | + ```shell |
| 102 | + git branch -D my-fix-branch |
| 103 | + ``` |
| 104 | +
|
| 105 | +* Update your master with the latest upstream version: |
| 106 | +
|
| 107 | + ```shell |
| 108 | + git pull --ff upstream master |
| 109 | + ``` |
| 110 | +
|
| 111 | +
|
| 112 | +- [Submitting a Pull Request (PR)](#submitting-a-pull-request-pr) |
| 113 | +## Commit Message Guidelines |
| 114 | +
|
| 115 | +We have very precise rules over how our git commit messages can be formatted. This leads to **more |
| 116 | +readable messages** that are easy to follow when looking through the **project history**. But also, |
| 117 | +we use the git commit messages to **generate the rxjs-docs change log**. Helper script `npm run commit` |
| 118 | +provides command line based wizard to format commit message easily. |
| 119 | +
|
| 120 | +### Commit Message Format |
| 121 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 122 | +format that includes a **type**, a **scope** and a **subject**: |
| 123 | +
|
| 124 | +``` |
| 125 | +<type>(<scope>): <subject> |
| 126 | +<BLANK LINE> |
| 127 | +<body> |
| 128 | +<BLANK LINE> |
| 129 | +<footer> |
| 130 | +``` |
| 131 | +
|
| 132 | +The **header** is mandatory and the **scope** of the header is optional. |
| 133 | +
|
| 134 | +Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier |
| 135 | +to read on GitHub as well as in various git tools. |
| 136 | +
|
| 137 | +### Revert |
| 138 | +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. |
| 139 | +
|
| 140 | +### Type |
| 141 | +Must be one of the following: |
| 142 | +
|
| 143 | +* **feat**: A new feature |
| 144 | +* **fix**: A bug fix |
| 145 | +* **docs**: Documentation only changes |
| 146 | +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing |
| 147 | + semi-colons, etc) |
| 148 | +* **refactor**: A code change that neither fixes a bug nor adds a feature |
| 149 | +* **perf**: A code change that improves performance |
| 150 | +* **test**: Adding missing tests |
| 151 | +* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation |
| 152 | + generation |
| 153 | +
|
| 154 | +### Scope |
| 155 | +The scope could be anything specifying place of the commit change. For example |
| 156 | +`Observable`, `Subject`, `switchMap`, etc. |
| 157 | +
|
| 158 | +### Subject |
| 159 | +The subject contains succinct description of the change: |
| 160 | +
|
| 161 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 162 | +* don't capitalize first letter |
| 163 | +* no dot (.) at the end |
| 164 | + |
| 165 | +### Body |
| 166 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 167 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 168 | + |
| 169 | +### Footer |
| 170 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 171 | +reference GitHub issues that this commit **Closes**. |
| 172 | + |
| 173 | +**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. |
0 commit comments