github.com/google/go-github/v53@v53.2.0/CONTRIBUTING.md (about) 1 # How to contribute # 2 3 We'd love to accept your patches and contributions to this project. There are 4 a just a few small guidelines you need to follow. 5 6 7 ## Contributor License Agreement ## 8 9 Contributions to any Google project must be accompanied by a Contributor 10 License Agreement. This is not a copyright **assignment**, it simply gives 11 Google permission to use and redistribute your contributions as part of the 12 project. Head over to <https://cla.developers.google.com/> to see your current 13 agreements on file or to sign a new one. 14 15 You generally only need to submit a CLA once, so if you've already submitted one 16 (even if it was for a different project), you probably don't need to do it 17 again. 18 19 20 ## Reporting issues ## 21 22 Bugs, feature requests, and development-related questions should be directed to 23 our [GitHub issue tracker](https://github.com/google/go-github/issues). If 24 reporting a bug, please try and provide as much context as possible such as 25 your operating system, Go version, and anything else that might be relevant to 26 the bug. For feature requests, please explain what you're trying to do, and 27 how the requested feature would help you do that. 28 29 Security related bugs can either be reported in the issue tracker, or if they 30 are more sensitive, emailed to <opensource@google.com>. 31 32 ## Submitting a patch ## 33 34 1. It's generally best to start by opening a new issue describing the bug or 35 feature you're intending to fix. Even if you think it's relatively minor, 36 it's helpful to know what people are working on. Mention in the initial 37 issue that you are planning to work on that bug or feature so that it can 38 be assigned to you. 39 40 1. Follow the normal process of [forking][] the project, and setup a new 41 branch to work in. It's important that each group of changes be done in 42 separate branches in order to ensure that a pull request only includes the 43 commits related to that bug or feature. 44 45 1. Go makes it very simple to ensure properly formatted code, so always run 46 `go fmt` on your code before committing it. You should also run 47 [go vet][] over your code. this will help you find common style issues 48 within your code and will keep styling consistent within the project. 49 50 1. Any significant changes should almost always be accompanied by tests. The 51 project already has good test coverage, so look at some of the existing 52 tests if you're unsure how to go about it. [gocov][] and [gocov-html][] 53 are invaluable tools for seeing which parts of your code aren't being 54 exercised by your tests. 55 56 1. Please run: 57 * `go generate github.com/google/go-github/...` 58 * `go test github.com/google/go-github/...` 59 * `go vet github.com/google/go-github/...` 60 61 The `go generate ./...` command will update or generate certain files, and the 62 resulting changes should be included in your pull request. 63 64 The `go test ./...` command will run tests inside your code. This will help you 65 spot places where code might be faulty before committing. 66 67 And finally, the `go vet ./...` command will check linting and styling over your 68 code, keeping the project consistent formatting-wise. 69 70 In any case, it is always a good idea to read [official Go documentation][] when working 71 on this project, as the definition of tools and commands of the Go programming 72 language is described in further detail there. 73 74 1. Do your best to have [well-formed commit messages][] for each change. 75 This provides consistency throughout the project, and ensures that commit 76 messages are able to be formatted properly by various git tools. 77 78 1. Finally, push the commits to your fork and submit a [pull request][]. 79 Before pushing commits, it is highly advised to check for generated files 80 that were either created or modified for the sake of your commit. Running 81 `go generate -x ./...` should return a log of modified generated files that should 82 be included alongside the manually written code in the commit. 83 **NOTE:** Please do not use force-push on PRs in this repo, as it makes 84 it more difficult for reviewers to see what has changed since the last 85 code review. 86 87 [official Go documentation]: https://pkg.go.dev/std 88 [forking]: https://help.github.com/articles/fork-a-repo 89 [go vet]: https://pkg.go.dev/cmd/vet 90 [gocov]: https://github.com/axw/gocov 91 [gocov-html]: https://github.com/matm/gocov-html 92 [well-formed commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 93 [squash]: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits 94 [pull request]: https://help.github.com/articles/creating-a-pull-request 95 96 97 ## Other notes on code organization ## 98 99 Currently, everything is defined in the main `github` package, with API methods 100 broken into separate service objects. These services map directly to how 101 the [GitHub API documentation][] is organized, so use that as your guide for 102 where to put new methods. 103 104 Code is organized in files also based pretty closely on the GitHub API 105 documentation, following the format `{service}_{api}.go`. For example, methods 106 defined at <https://docs.github.com/en/rest/webhooks/repos> live in 107 [repos_hooks.go][]. 108 109 [GitHub API documentation]: https://docs.github.com/en/rest 110 [repos_hooks.go]: https://github.com/google/go-github/blob/master/github/repos_hooks.go 111 112 113 ## Maintainer's Guide ## 114 115 (These notes are mostly only for people merging in pull requests.) 116 117 **Verify CLAs.** CLAs must be on file for the pull request submitter and commit 118 author(s). Google's CLA verification system should handle this automatically 119 and will set commit statuses as appropriate. If there's ever any question about 120 a pull request, ask [willnorris](https://github.com/willnorris). 121 122 **Always try to maintain a clean, linear git history.** With very few 123 exceptions, running `git log` should not show a bunch of branching and merging. 124 125 Never use the GitHub "merge" button, since it always creates a merge commit. 126 Instead, check out the pull request locally ([these git aliases 127 help][git-aliases]), then cherry-pick or rebase them onto master. If there are 128 small cleanup commits, especially as a result of addressing code review 129 comments, these should almost always be squashed down to a single commit. Don't 130 bother squashing commits that really deserve to be separate though. If needed, 131 feel free to amend additional small changes to the code or commit message that 132 aren't worth going through code review for. 133 134 If you made any changes like squashing commits, rebasing onto master, etc, then 135 GitHub won't recognize that this is the same commit in order to mark the pull 136 request as "merged". So instead, amend the commit message to include a line 137 "Fixes #0", referencing the pull request number. This would be in addition to 138 any other "Fixes" lines for closing related issues. If you forget to do this, 139 you can also leave a comment on the pull request [like this][rebase-comment]. 140 If you made any other changes, it's worth noting that as well, [like 141 this][modified-comment]. 142 143 [git-aliases]: https://github.com/willnorris/dotfiles/blob/d640d010c23b1116bdb3d4dc12088ed26120d87d/git/.gitconfig#L13-L15 144 [rebase-comment]: https://github.com/google/go-github/pull/277#issuecomment-183035491 145 [modified-comment]: https://github.com/google/go-github/pull/280#issuecomment-184859046 146 147 **When creating a release, don't forget to update the `Version` constant in `github.go`.** This is used to 148 send the version in the `User-Agent` header to identify clients to the GitHub API.