|
| 1 | +# Pull Request Guidelines |
| 2 | + |
| 3 | +Here you will find step by step guidance for creating, submitting and updating |
| 4 | +a pull request in this repository. We hope it will help you have an easy time |
| 5 | +managing your work and a positive, satisfying experience when contributing |
| 6 | +your code. Thanks for getting involved! :rocket: |
| 7 | + |
| 8 | +* [Getting Started](#getting-started) |
| 9 | +* [Branches](#branches) |
| 10 | +* [Commit Messages](#commit-messages) |
| 11 | +* [Staying current with master](#staying-current-with-master) |
| 12 | +* [Style Guide](#style-guide) |
| 13 | +* [Submitting and Updating a Pull Request](#submitting-and-updating-a-pull-request) |
| 14 | +* [Congratulations!](#congratulations) |
| 15 | + |
| 16 | +## Getting Started |
| 17 | + |
| 18 | +When creating a pull request, first fork this repository and clone it to your |
| 19 | +local development environment. Then add this repository as the upstream. |
| 20 | + |
| 21 | +```console |
| 22 | +git clone https://github.com/mygithuborg/sdk-javascript.git |
| 23 | +cd sdk-javascript |
| 24 | +git remote add upstream https://github.com/cloudevents/sdk-javascript.git |
| 25 | +``` |
| 26 | + |
| 27 | +## Branches |
| 28 | + |
| 29 | +The first thing you'll need to do is create a branch for your work. |
| 30 | +If you are submitting a pull request that fixes or relates to an existing |
| 31 | +GitHub issue, you can use this in your branch name to keep things organized. |
| 32 | +For example, if you were to create a pull request to fix |
| 33 | +[this error with `httpAgent`](https://github.com/cloudevents/sdk-javascript/issues/48) |
| 34 | +you might create a branch named `48-fix-http-agent-error`. |
| 35 | + |
| 36 | +```console |
| 37 | +git fetch upstream |
| 38 | +git reset --hard upstream/master |
| 39 | +git checkout -b 48-fix-http-agent-error |
| 40 | +``` |
| 41 | + |
| 42 | +## Commit Messages |
| 43 | + |
| 44 | +Please follow the |
| 45 | +[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary). |
| 46 | +The first line of your commit should be prefixed with a type, be a single |
| 47 | +sentence with no period, and succinctly indicate what this commit changes. |
| 48 | + |
| 49 | +All commit message lines should be kept to fewer than 80 characters if possible. |
| 50 | + |
| 51 | +An example of a good commit message. |
| 52 | + |
| 53 | +```log |
| 54 | +docs: remove 0.1, 0.2 spec support from README |
| 55 | +``` |
| 56 | + |
| 57 | +If you are unsure what prefix to use for a commit, you can consult the |
| 58 | +[package.json](package.json) file. |
| 59 | +In the `standard-version.types` section, you can see all of the commit |
| 60 | +types that will be committed to the changelog based on the prefix in the first line of |
| 61 | +your commit message. For example, the commit message: |
| 62 | + |
| 63 | +```log |
| 64 | +fix: removed a bug that was causing the rotation of the earth to change |
| 65 | +``` |
| 66 | + |
| 67 | +will show up in the "Bug Fixes" section of the changelog for a given release. |
| 68 | + |
| 69 | +### Signing your commits |
| 70 | + |
| 71 | +Each commit must be signed. Use the `--signoff` flag for your commits. |
| 72 | + |
| 73 | +```console |
| 74 | +git commit --signoff |
| 75 | +``` |
| 76 | + |
| 77 | +This will add a line to every git commit message: |
| 78 | + |
| 79 | + Signed-off-by: Joe Smith <joe.smith@email.com> |
| 80 | + |
| 81 | +Use your real name (sorry, no pseudonyms or anonymous contributions.) |
| 82 | + |
| 83 | +The sign-off is a signature line at the end of your commit message. Your |
| 84 | +signature certifies that you wrote the patch or otherwise have the right to pass |
| 85 | +it on as open-source code. See [developercertificate.org](http://developercertificate.org/)) |
| 86 | +for the full text of the certification. |
| 87 | + |
| 88 | +Be sure to have your `user.name` and `user.email` set in your git config. |
| 89 | +If your git config information is set properly then viewing the `git log` |
| 90 | +information for your commit will look something like this: |
| 91 | + |
| 92 | +``` |
| 93 | +Author: Joe Smith <joe.smith@email.com> |
| 94 | +Date: Thu Feb 2 11:41:15 2018 -0800 |
| 95 | +
|
| 96 | + Update README |
| 97 | +
|
| 98 | + Signed-off-by: Joe Smith <joe.smith@email.com> |
| 99 | +``` |
| 100 | + |
| 101 | +Notice the `Author` and `Signed-off-by` lines match. If they don't your PR will |
| 102 | +be rejected by the automated DCO check. |
| 103 | + |
| 104 | +## Staying Current with `master` |
| 105 | + |
| 106 | +As you are working on your branch, changes may happen on `master`. Before |
| 107 | +submitting your pull request, be sure that your branch has been updated |
| 108 | +with the latest commits. |
| 109 | + |
| 110 | +```console |
| 111 | +git fetch upstream |
| 112 | +git rebase upstream/master |
| 113 | +``` |
| 114 | + |
| 115 | +This may cause conflicts if the files you are changing on your branch are |
| 116 | +also changed on master. Error messages from `git` will indicate if conflicts |
| 117 | +exist and what files need attention. Resolve the conflicts in each file, then |
| 118 | +continue with the rebase with `git rebase --continue`. |
| 119 | + |
| 120 | + |
| 121 | +If you've already pushed some changes to your `origin` fork, you'll |
| 122 | +need to force push these changes. |
| 123 | + |
| 124 | +```console |
| 125 | +git push -f origin 48-fix-http-agent-error |
| 126 | +``` |
| 127 | + |
| 128 | +## Style Guide |
| 129 | + |
| 130 | +Code style for this module is maintained using [`eslint`](https://www.npmjs.com/package/eslint). |
| 131 | +When you run tests with `npm test` linting is performed first. If you want to |
| 132 | +check your code style for linting errors without running tests, you can just |
| 133 | +run `npm run lint`. If there are errors, you can usually fix them automatically |
| 134 | +by running `npm run fix`. |
| 135 | + |
| 136 | +Linting rules are declared in [.eslintrc](https://github.com/cloudevents/sdk-javascript/blob/master/.eslintrc). |
| 137 | + |
| 138 | +## Submitting and Updating Your Pull Request |
| 139 | + |
| 140 | +Before submitting a pull request, you should make sure that all of the tests |
| 141 | +successfully pass by running `npm test`. |
| 142 | + |
| 143 | +Once you have sent your pull request, `master` may continue to evolve |
| 144 | +before your pull request has landed. If there are any commits on `master` |
| 145 | +that conflict with your changes, you may need to update your branch with |
| 146 | +these changes before the pull request can land. Resolve conflicts the same |
| 147 | +way as before. |
| 148 | + |
| 149 | +```console |
| 150 | +git fetch upstream |
| 151 | +git rebase upstream/master |
| 152 | +# fix any potential conflicts |
| 153 | +git push -f origin 48-fix-http-agent-error |
| 154 | +``` |
| 155 | + |
| 156 | +This will cause the pull request to be updated with your changes, and |
| 157 | +CI will rerun. |
| 158 | + |
| 159 | +A maintainer may ask you to make changes to your pull request. Sometimes these |
| 160 | +changes are minor and shouldn't appear in the commit log. For example, you may |
| 161 | +have a typo in one of your code comments that should be fixed before merge. |
| 162 | +You can prevent this from adding noise to the commit log with an interactive |
| 163 | +rebase. See the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) |
| 164 | +for details. |
| 165 | + |
| 166 | +```console |
| 167 | +git commit -m "fixup: fix typo" |
| 168 | +git rebase -i upstream/master # follow git instructions |
| 169 | +``` |
| 170 | + |
| 171 | +Once you have rebased your commits, you can force push to your fork as before. |
| 172 | + |
| 173 | +## Congratulations! |
| 174 | + |
| 175 | +Congratulations! You've done it! We really appreciate the time and energy |
| 176 | +you've given to the project. Thank you. |
0 commit comments