1# How to contribute
2
3Thank you for your contribution to grpc-gateway.
4Here's the recommended process of contribution.
5
61. `go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway`
71. `cd $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway`
81. hack, hack, hack...
91. Make sure that your change follows best practices in Go
10 - [Effective Go](https://golang.org/doc/effective_go.html)
11 - [Go Code Review Comments](https://golang.org/wiki/CodeReviewComments)
121. Make sure that `go test ./...` passes.
131. Sign [a Contributor License Agreement](https://cla.developers.google.com/clas)
141. Open a pull request in GitHub
15
16When you work on a larger contribution, it is also recommended that you get in touch
17with us through the issue tracker.
18
19### Code reviews
20
21All submissions, including submissions by project members, require review.
22
23### I want to regenerate the files after making changes
24
25#### Using Docker
26
27It should be as simple as this (run from the root of the repository):
28
29```bash
30docker run -v $(pwd):/src/grpc-gateway --rm docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env:1.15 \
31 /bin/bash -c 'cd /src/grpc-gateway && \
32 make realclean && \
33 make examples && \
34 make testproto'
35docker run -itv $(pwd):/grpc-gateway -w /grpc-gateway --entrypoint /bin/bash --rm \
36 l.gcr.io/google/bazel -c '\
37 bazel run :gazelle -- update-repos -from_file=go.mod -to_macro=repositories.bzl%go_repositories && \
38 bazel run :gazelle && \
39 bazel run :buildifier'
40```
41
42You may need to authenticate with GitHub to pull `docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env`.
43You can do this by following the steps on the [GitHub Package docs](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-to-github-packages).
44
45#### Using Visual Studio Code dev containers
46
47This repo contains a `devcontainer.json` configuration that sets up the build environment in a container using
48[VS Code dev containers](https://code.visualstudio.com/docs/remote/containers). If you're using the dev container,
49you can run the commands directly in your terminal:
50
51```shell
52$ make realclean && make examples && make testproto
53```
54
55```shell
56$ bazel run :gazelle -- update-repos -from_file=go.mod -to_macro=repositories.bzl%go_repositories && \
57 bazel run :gazelle && \
58 bazel run :buildifier
59```
60
61Note that the above listed docker commands will not work in the dev container, since volume mounts from
62nested docker container are not possible.
63
64If this has resulted in some file changes in the repo, please ensure you check those in with your merge request.
65
66### Making a release
67
68To make a release, follow these steps:
69
701. Decide on a release version. The `gorelease` job can
71 recommend whether the new release should be a patch or minor release.
72 See [CircleCI](https://app.circleci.com/pipelines/github/grpc-ecosystem/grpc-gateway/126/workflows/255a8a04-de9c-46a9-a66b-f107d2b39439/jobs/6428)
73 for an example.
741. Generate a GitHub token with `repo` access.
751. Create a new branch and edit the Makefile `changelog` job, settings
76 the `future-release=` variable to the name of the version you plan to release
771. Run `CHANGELOG_GITHUB_TOKEN=<yourtoken> make changelog`
781. Commit the `Makefile` and `CHANGELOG.md` changes.
791. Open a PR and check that everything looks right.
801. Merge the PR.
811. Tag the release on `v1`, the tag should be made against the commit you just merged.
82 1. The release can be created using the command line, or also through GitHub's [releases
83 UI](https://github.com/grpc-ecosystem/grpc-gateway/releases/new).
84 1. If you create a release using the web UI you can publish it as a draft and have it
85 reviewed by another maintainer.
861. (Optional) Delete your GitHub token again.
871. (Required) Sit back and pat yourself on the back for a job well done :clap:.
View as plain text