github.com/google/go-github/v49@v49.1.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       [golint][] over your code. As noted in the [golint readme][], it's not
    48       strictly necessary that your code be completely "lint-free", but this will
    49       help you find common style issues.
    50  
    51    1. Any significant changes should almost always be accompanied by tests. The
    52       project already has good test coverage, so look at some of the existing
    53       tests if you're unsure how to go about it. [gocov][] and [gocov-html][]
    54       are invaluable tools for seeing which parts of your code aren't being
    55       exercised by your tests.
    56  
    57    1. Please run:
    58       * `go generate github.com/google/go-github/...`
    59       * `go test github.com/google/go-github/...`
    60       * `go vet github.com/google/go-github/...`
    61  
    62    1. Do your best to have [well-formed commit messages][] for each change.
    63       This provides consistency throughout the project, and ensures that commit
    64       messages are able to be formatted properly by various git tools.
    65  
    66    1. Finally, push the commits to your fork and submit a [pull request][].
    67       **NOTE:** Please do not use force-push on PRs in this repo, as it makes
    68       it more difficult for reviewers to see what has changed since the last
    69       code review.
    70  
    71  [forking]: https://help.github.com/articles/fork-a-repo
    72  [golint]: https://github.com/golang/lint
    73  [golint readme]: https://github.com/golang/lint/blob/master/README.md
    74  [gocov]: https://github.com/axw/gocov
    75  [gocov-html]: https://github.com/matm/gocov-html
    76  [well-formed commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
    77  [squash]: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits
    78  [pull request]: https://help.github.com/articles/creating-a-pull-request
    79  
    80  
    81  ## Other notes on code organization ##
    82  
    83  Currently, everything is defined in the main `github` package, with API methods
    84  broken into separate service objects. These services map directly to how
    85  the [GitHub API documentation][] is organized, so use that as your guide for
    86  where to put new methods.
    87  
    88  Code is organized in files also based pretty closely on the GitHub API
    89  documentation, following the format `{service}_{api}.go`. For example, methods
    90  defined at <https://docs.github.com/en/rest/webhooks/repos> live in
    91  [repos_hooks.go][].
    92  
    93  [GitHub API documentation]: https://docs.github.com/en/rest
    94  [repos_hooks.go]: https://github.com/google/go-github/blob/master/github/repos_hooks.go
    95  
    96  
    97  ## Maintainer's Guide ##
    98  
    99  (These notes are mostly only for people merging in pull requests.)
   100  
   101  **Verify CLAs.** CLAs must be on file for the pull request submitter and commit
   102  author(s). Google's CLA verification system should handle this automatically
   103  and will set commit statuses as appropriate. If there's ever any question about
   104  a pull request, ask [willnorris](https://github.com/willnorris).
   105  
   106  **Always try to maintain a clean, linear git history.** With very few
   107  exceptions, running `git log` should not show a bunch of branching and merging.
   108  
   109  Never use the GitHub "merge" button, since it always creates a merge commit.
   110  Instead, check out the pull request locally ([these git aliases
   111  help][git-aliases]), then cherry-pick or rebase them onto master. If there are
   112  small cleanup commits, especially as a result of addressing code review
   113  comments, these should almost always be squashed down to a single commit. Don't
   114  bother squashing commits that really deserve to be separate though. If needed,
   115  feel free to amend additional small changes to the code or commit message that
   116  aren't worth going through code review for.
   117  
   118  If you made any changes like squashing commits, rebasing onto master, etc, then
   119  GitHub won't recognize that this is the same commit in order to mark the pull
   120  request as "merged". So instead, amend the commit message to include a line
   121  "Fixes #0", referencing the pull request number. This would be in addition to
   122  any other "Fixes" lines for closing related issues. If you forget to do this,
   123  you can also leave a comment on the pull request [like this][rebase-comment].
   124  If you made any other changes, it's worth noting that as well, [like
   125  this][modified-comment].
   126  
   127  [git-aliases]: https://github.com/willnorris/dotfiles/blob/d640d010c23b1116bdb3d4dc12088ed26120d87d/git/.gitconfig#L13-L15
   128  [rebase-comment]: https://github.com/google/go-github/pull/277#issuecomment-183035491
   129  [modified-comment]: https://github.com/google/go-github/pull/280#issuecomment-184859046
   130  
   131  **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.