1# How to contribute #
2
3We'd love to accept your patches and contributions to this project. There are
4a just a few small guidelines you need to follow.
5
6
7## Contributor License Agreement ##
8
9Contributions to any Google project must be accompanied by a Contributor
10License Agreement. This is not a copyright **assignment**, it simply gives
11Google permission to use and redistribute your contributions as part of the
12project. Head over to <https://cla.developers.google.com/> to see your current
13agreements on file or to sign a new one.
14
15You 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
17again.
18
19
20## Reporting issues ##
21
22Bugs, feature requests, and development-related questions should be directed to
23our [GitHub issue tracker](https://github.com/google/go-github/issues). If
24reporting a bug, please try and provide as much context as possible such as
25your operating system, Go version, and anything else that might be relevant to
26the bug. For feature requests, please explain what you're trying to do, and
27how the requested feature would help you do that.
28
29Security related bugs can either be reported in the issue tracker, or if they
30are 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
99Currently, everything is defined in the main `github` package, with API methods
100broken into separate service objects. These services map directly to how
101the [GitHub API documentation][] is organized, so use that as your guide for
102where to put new methods.
103
104Code is organized in files also based pretty closely on the GitHub API
105documentation, following the format `{service}_{api}.go`. For example, methods
106defined 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
118author(s). Google's CLA verification system should handle this automatically
119and will set commit statuses as appropriate. If there's ever any question about
120a pull request, ask [willnorris](https://github.com/willnorris).
121
122**Always try to maintain a clean, linear git history.** With very few
123exceptions, running `git log` should not show a bunch of branching and merging.
124
125Never use the GitHub "merge" button, since it always creates a merge commit.
126Instead, check out the pull request locally ([these git aliases
127help][git-aliases]), then cherry-pick or rebase them onto master. If there are
128small cleanup commits, especially as a result of addressing code review
129comments, these should almost always be squashed down to a single commit. Don't
130bother squashing commits that really deserve to be separate though. If needed,
131feel free to amend additional small changes to the code or commit message that
132aren't worth going through code review for.
133
134If you made any changes like squashing commits, rebasing onto master, etc, then
135GitHub won't recognize that this is the same commit in order to mark the pull
136request 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
138any other "Fixes" lines for closing related issues. If you forget to do this,
139you can also leave a comment on the pull request [like this][rebase-comment].
140If you made any other changes, it's worth noting that as well, [like
141this][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
148send the version in the `User-Agent` header to identify clients to the GitHub API.
View as plain text