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