Skip to content

Latest commit

 

History

History
148 lines (112 loc) · 7.37 KB

CONTRIBUTING.md

File metadata and controls

148 lines (112 loc) · 7.37 KB
Raw

How to contribute

We'd love to accept your patches and contributions to this project. There are a just a few small guidelines you need to follow.

Contributor License Agreement

Contributions to any Google project must be accompanied by a Contributor License Agreement. This is not a copyright assignment, it simply gives Google permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Reporting issues

Bugs, feature requests, and development-related questions should be directed to our GitHub issue tracker. If reporting a bug, please try and provide as much context as possible such as your operating system, Go version, and anything else that might be relevant to the bug. For feature requests, please explain what you're trying to do, and how the requested feature would help you do that.

Security related bugs can either be reported in the issue tracker, or if they are more sensitive, emailed to [email protected].

Submitting a patch

  1. It's generally best to start by opening a new issue describing the bug or feature you're intending to fix. Even if you think it's relatively minor, it's helpful to know what people are working on. Mention in the initial issue that you are planning to work on that bug or feature so that it can be assigned to you.

  2. Follow the normal process of forking the project, and setup a new branch to work in. It's important that each group of changes be done in separate branches in order to ensure that a pull request only includes the commits related to that bug or feature.

  3. Go makes it very simple to ensure properly formatted code, so always run go fmt on your code before committing it. You should also run go vet over your code. this will help you find common style issues within your code and will keep styling consistent within the project.

  4. Any significant changes should almost always be accompanied by tests. The project already has good test coverage, so look at some of the existing tests if you're unsure how to go about it. gocov and gocov-html are invaluable tools for seeing which parts of your code aren't being exercised by your tests.

  5. Please run:

    • go generate github.com/google/go-github/...
    • go test github.com/google/go-github/...
    • go vet github.com/google/go-github/...

The go generate ./... command will update or generate certain files, and the resulting changes should be included in your pull request.

The go test ./... command will run tests inside your code. This will help you spot places where code might be faulty before committing.

And finally, the go vet ./... command will check linting and styling over your code, keeping the project consistent formatting-wise.

In any case, it is always a good idea to read official Go documentation when working on this project, as the definition of tools and commands of the Go programming language is described in further detail there.

  1. Do your best to have well-formed commit messages for each change. This provides consistency throughout the project, and ensures that commit messages are able to be formatted properly by various git tools.

  2. Finally, push the commits to your fork and submit a pull request. Before pushing commits, it is highly advised to check for generated files that were either created or modified for the sake of your commit. Running go generate -x ./... should return a log of modified generated files that should be included alongside the manually written code in the commit. NOTE: Please do not use force-push on PRs in this repo, as it makes it more difficult for reviewers to see what has changed since the last code review.

Other notes on code organization

Currently, everything is defined in the main github package, with API methods broken into separate service objects. These services map directly to how the GitHub API documentation is organized, so use that as your guide for where to put new methods.

Code is organized in files also based pretty closely on the GitHub API documentation, following the format {service}_{api}.go. For example, methods defined at https://docs.github.com/en/rest/webhooks/repos live in repos_hooks.go.

Maintainer's Guide

(These notes are mostly only for people merging in pull requests.)

Verify CLAs. CLAs must be on file for the pull request submitter and commit author(s). Google's CLA verification system should handle this automatically and will set commit statuses as appropriate. If there's ever any question about a pull request, ask willnorris.

Always try to maintain a clean, linear git history. With very few exceptions, running git log should not show a bunch of branching and merging.

Never use the GitHub "merge" button, since it always creates a merge commit. Instead, check out the pull request locally (these git aliases help), then cherry-pick or rebase them onto master. If there are small cleanup commits, especially as a result of addressing code review comments, these should almost always be squashed down to a single commit. Don't bother squashing commits that really deserve to be separate though. If needed, feel free to amend additional small changes to the code or commit message that aren't worth going through code review for.

If you made any changes like squashing commits, rebasing onto master, etc, then GitHub won't recognize that this is the same commit in order to mark the pull request as "merged". So instead, amend the commit message to include a line "Fixes #0", referencing the pull request number. This would be in addition to any other "Fixes" lines for closing related issues. If you forget to do this, you can also leave a comment on the pull request like this. If you made any other changes, it's worth noting that as well, like this.

When creating a release, don't forget to update the Version constant in github.go. This is used to send the version in the User-Agent header to identify clients to the GitHub API.