agones.dev/agones@v1.54.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 just a few small guidelines you need to follow. 5 6 ## Contributor License Agreement 7 8 Contributions to this project must be accompanied by a Contributor License 9 Agreement. You (or your employer) retain the copyright to your contribution, 10 this simply gives us permission to use and redistribute your contributions as 11 part of the project. Head over to <https://cla.developers.google.com/> to see 12 your current agreements on file or to sign a new one. 13 14 You generally only need to submit a CLA once, so if you've already submitted one 15 (even if it was for a different project), you probably don't need to do it 16 again. 17 18 ## Code of Conduct 19 20 Participation in this project comes under the [Contributor Covenant Code of Conduct](code-of-conduct.md) 21 22 ## Finding Issues to Work On 23 24 If you're new to the project and want to help, but don't know where to start, look for issues labeled with: 25 26 - **[good first issue](https://github.com/googleforgames/agones/labels/good%20first%20issue)** - These are great for 27 people who are new to the project. They are typically smaller in scope and easier to tackle. 28 - **[help wanted](https://github.com/googleforgames/agones/labels/help%20wanted)** - These issues are ready for 29 contributions and often include good first issues, but may also involve more complex work for those who want to dig a 30 little deeper. 31 32 These labels help you find issues that are well-suited for external contributions and where maintainers are actively 33 looking for help. 34 35 ## Submitting code via Pull Requests 36 37 *Thank you* for considering submitting code to Agones! 38 39 - We follow the [GitHub Pull Request Model](https://help.github.com/articles/about-pull-requests/) for 40 all contributions. 41 - For large bodies of work, we recommend creating an issue and labelling it 42 "[kind/design](https://github.com/googleprivate/agones/issues?q=is%3Aissue+is%3Aopen+label%3Akind%2Fdesign)" 43 outlining the feature that you wish to build, and describing how it will be implemented. This gives a chance 44 for review to happen early, and ensures no wasted effort occurs. 45 - For new features, documentation *must* be included. Review the [Documentation Editing and Contribution](https://agones.dev/site/docs/contribute/) 46 guide for details. 47 - It is strongly recommended that new API design follows the [Google AIPs](https://google.aip.dev/) design guidelines. 48 - All submissions, including submissions by project members, will require review before being merged. 49 - Once review has occurred, please rebase your PR down to a single commit. This will ensure a nice clean Git history. 50 - If you are unable to access build errors from your PR, make sure that you have joined the [agones-discuss mailing list](https://groups.google.com/forum/#!forum/agones-discuss). 51 - Please follow the code formatting instructions below. 52 53 ### Additional Instructions for Unreal Plugin Pull Requests 54 55 As there is no CI for the Unreal plugin, the following checklist should be run 56 manually before the PR is approved, using the latest released version of UE4. 57 58 1. Create default C++ template project in UE4. 59 1. Create a Plugins folder under the project directory (should be a sibling of the .uproject file). 60 1. Copy the [sdks/unreal/Agones](sdks/unreal/Agones) directory into the Plugins folder. 61 1. Build the UE4 project. 62 1. If the build succeeded, paste the build logs into the PR. 63 64 ## Formatting 65 66 When submitting pull requests, make sure to do the following: 67 68 - Format all Go code with [gofmt](https://golang.org/cmd/gofmt/). Many people 69 use [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) which 70 fixes import statements and formats code in the same style of `gofmt`. 71 - C++ code should follow the [Google C++ Style 72 Guide](https://google.github.io/styleguide/cppguide.html), which can be 73 applied automatically using the 74 [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) command-line tool 75 (e.g., `clang-format -style=Google foo.cc`). The exception to this is 76 the [Unreal Engine plugin code](sdks/unreal/Agones), which should follow the 77 [Unreal Engine 4 Coding Standard](https://docs.unrealengine.com/en-US/Programming/Development/CodingStandard/index.html). 78 - Remove trailing whitespace. Many editors will do this automatically. 79 - Ensure any new files have [a trailing newline](https://stackoverflow.com/questions/5813311/no-newline-at-end-of-file) 80 81 ## Feature Stages 82 83 Often, new features will need to go through experimental stages so that we can gather feedback and adjust as necessary. 84 85 You can see this project's [feature stage documentation](https://agones.dev/site/docs/guides/feature-stages/) on the Agones 86 website. 87 88 If you are working on a new feature, you may need to take feature stages into account. This should be discussed on a 89 design ticket prior to commencement of work. 90 91 ## Continuous Integration 92 93 Continuous integration is provided by [Google Cloud Container Builder](https://cloud.google.com/container-builder/), 94 through the [cloudbuilder.yaml](./cloudbuild.yaml) file found at the root of the directory. 95 96 Build success/failure with relevant details are pushed automatically to pull requests via [agones-bot](./build/agones-bot/README.md). 97 98 See the [Container Builder documentation](https://cloud.google.com/container-builder/docs/) for more details on 99 how to edit and expand the build process. 100 101 ## Kubernetes Versions Update 102 ### When to update supported Kubernetes Versions 103 As documented in the [version update policy](https://agones.dev/site/docs/installation/#agones-and-kubernetes-supported-versions), each version of Agones supports 3 releases of Kubernetes. The newest supported version is the latest available version in the GKE Rapid channel and at least one of the 3 supported version is supported by each of the major cloud providers (EKS and AKS). This means whenever a new minor version is available in the [GKE Rapid channel](https://cloud.google.com/kubernetes-engine/docs/release-notes-rapid), we should check whether we can roll forward the supported versions. 104 ### How to update supported Kubernetes Versions 105 Please follow the steps below to update the Kubernetes versions supported. 106 107 1. Create a Issue from the [kubernetes update issue template](./.github/ISSUE_TEMPLATE/kubernetes_update.md) with the newly supported versions. 108 2. Complete all items in the issue checklist. 109 3. Close the issue. 110 111 112 ## Community Meetings 113 114 Community meetings occur every month, and are open to all who wish to attend! 115 116 You can see them on our calendar 117 ([web](https://calendar.google.com/calendar/embed?src=google.com_828n8f18hfbtrs4vu4h1sks218%40group.calendar.google.com&ctz=America%2FLos_Angeles), 118 [ical](https://calendar.google.com/calendar/ical/google.com_828n8f18hfbtrs4vu4h1sks218%40group.calendar.google.com/public/basic.ics)) and/or join the 119 [mailing list or Slack](https://agones.dev/site/community/) 120 for notifications. 121 122 ## Becoming a Collaborator on Agones 123 124 If you have submitted at least one Pull Request and had it merged, you may wish to become an official collaborator. 125 This will give you the ability to have tickets assigned to you (or you can assign tickets to yourself!). 126 127 We have a [community membership guide](./docs/governance/community_membership.md), that outlines the process. 128 129 ## Becoming an Approver on Agones 130 131 If you are interested in becoming an Approver on the Agones project and getting commit access to the 132 repository, we have a [community membership guide](./docs/governance/community_membership.md), that outlines the process. 133 134 ### Additional Resources 135 136 #### Extending Kubernetes 137 138 - [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/api-extension/custom-resources/) - 139 This is how we define our own resource names (`GameServer`, etc) within Kubernetes. 140 - [Kubernetes Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) - 141 Kubernetes documentation on writing controllers. 142 - [Extend the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/) - 143 This page shows how to install a custom resource into the Kubernetes API by creating a CustomResourceDefinition. 144 - [Joe Beda's TGIK Controller](https://github.com/jbeda/tgik-controller) - 145 [Joe Beda](https://twitter.com/jbeda) did a video series on writing controllers for Kubernetes. 146 **This is the best resource for learning about controllers and Kubernetes.** 147 - [Kubernetes Sample Controller](https://github.com/kubernetes/sample-controller) - 148 Example of a Custom Resources with a Kubernetes Controller. 149 - [Kubernetes Code Generator](https://github.com/kubernetes/code-generator) - 150 The tooling that generated the Go libraries for the Custom Resource we define 151 - [Kubernetes Controller Best Practices](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/controllers.md) - 152 Set of best practices written for writing Controllers inside Kubernetes. Also a great list for everywhere else too. 153 - [Writing Kube Controllers for Everyone - Maciej Szulik, Red Hat](https://www.youtube.com/watch?v=AUNPLQVxvmw) - 154 A great intro video into coding for Controllers, and explaining Informers and Listers. 155 - [@markmandel](https://github.com/markmandel) regularly streams his development of Agones on [Twitch](https://www.twitch.tv/markmandel). 156 You can find the full archive on [YouTube](https://www.youtube.com/playlist?list=PLqqp1QEhKwa5aNivDIE4SS21ehE9Zt0VZ) 157 158 159 #### Coding and Development 160 161 - [How to write a good Git Commit message](https://chris.beams.io/posts/git-commit/) - 162 Great way to make sure your Pull Requests get accepted. 163 - **Log levels usage:** 164 - Fatal - a critical error has happened and the application can not perform subsequent work anymore. Examples: missing configuration information in case there are no default values provided, one of the services can not start normally, etc. 165 - Error - a serious issue has happened, users are affected without having a way to work around one, but an application may continue to work. This error usually requires someone’s attention. Examples: a file cannot be opened, cannot respond to HTTP request properly, etc. 166 - Warn - something bad has happened, but the application still has the chance to heal itself or the issue can wait for some time to be fixed. Example: a system has failed to connect to an external resource but will try again automatically. 167 - Info - should be used to document state changes in the application or some entity within the application. These logs provide the skeleton of what has happened. Examples: system started/stopped, remote API calls, a new user has been created/updated, etc. 168 - Debug - diagnostic information goes here and everything that can help to troubleshoot an application. Examples: any values in business logic, detailed information about the data flow. 169 170 More details can be found in [this article](https://medium.com/@tom.hombergs/tip-use-logging-levels-consistently-913b7b8e9782).