How to Contribute

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

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us 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.

Code of Conduct

Participation in this project comes under the Contributor Covenant Code of Conduct

Submitting code via Pull Requests

Thank you for considering submitting code to Agones!

• We follow the GitHub Pull Request Model for all contributions.
• For large bodies of work, we recommend creating an issue and labelling it "kind/design" outlining the feature that you wish to build, and describing how it will be implemented. This gives a chance for review to happen early, and ensures no wasted effort occurs.
• For new features, documentation must be included. Review the Documentation Editing and Contribution guide for details.
• It is strongly recommended that new API design follows the Google AIPs design guidelines.
• All submissions, including submissions by project members, will require review before being merged.
• Once review has occurred, please rebase your PR down to a single commit. This will ensure a nice clean Git history.
• If you are unable to access build errors from your PR, make sure that you have joined the agones-discuss mailing list.
• Please follow the code formatting instructions below.

Additional Instructions for Unreal Plugin Pull Requests

As there is no CI for the Unreal plugin, the following checklist should be run manually before the PR is approved, using the latest released version of UE4.

1. Create default C++ template project in UE4.
2. Create a Plugins folder under the project directory (should be a sibling of the .uproject file).
3. Copy the sdks/unreal/Agones directory into the Plugins folder.
4. Build the UE4 project.
5. If the build succeeded, paste the build logs into the PR.

Formatting

When submitting pull requests, make sure to do the following:

• Format all Go code with gofmt. Many people use goimports which fixes import statements and formats code in the same style of gofmt.
• C++ code should follow the Google C++ Style Guide, which can be applied automatically using the ClangFormat command-line tool (e.g., clang-format -style=Google foo.cc). The exception to this is the Unreal Engine plugin code, which should follow the Unreal Engine 4 Coding Standard.
• Remove trailing whitespace. Many editors will do this automatically.
• Ensure any new files have a trailing newline

Feature Stages

Often, new features will need to go through experimental stages so that we can gather feedback and adjust as necessary.

You can see this project's feature stage documentation on the Agones website.

If you are working on a new feature, you may need to take feature stages into account. This should be discussed on a design ticket prior to commencement of work.

Continuous Integration

Continuous integration is provided by Google Cloud Container Builder, through the cloudbuilder.yaml file found at the root of the directory.

Build success/failure with relevant details are pushed automatically to pull requests via agones-bot.

See the Container Builder documentation for more details on how to edit and expand the build process.

Kubernetes Versions Update

When to update supported Kubernetes Versions

As documented in the version update policy, 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, we should check whether we can roll forward the supported versions.

How to update supported Kubernetes Versions

Please follow the steps below to update the Kubernetes versions supported.

1. Create a Issue from the kubernetes update issue template with the newly supported versions.
2. Complete all items in the issue checklist.
3. Close the issue.

Community Meetings

Community meetings occur every month, and are open to all who wish to attend!

You can see them on our calendar (web, ical) and/or join the mailing list or Slack for notifications.

Becoming a Collaborator on Agones

If you have submitted at least one Pull Request and had it merged, you may wish to become an official collaborator. This will give you the ability to have tickets assigned to you (or you can assign tickets to yourself!).

We have a community membership guide, that outlines the process.

Becoming an Approver on Agones

If you are interested in becoming an Approver on the Agones project and getting commit access to the repository, we have a community membership guide, that outlines the process.

Additional Resources

Extending Kubernetes

• Kubernetes Custom Resources - This is how we define our own resource names (GameServer, etc) within Kubernetes.
• Kubernetes Controllers - Kubernetes documentation on writing controllers.
• Extend the Kubernetes API with CustomResourceDefinitions - This page shows how to install a custom resource into the Kubernetes API by creating a CustomResourceDefinition.
• Joe Beda's TGIK Controller - Joe Beda did a video series on writing controllers for Kubernetes. This is the best resource for learning about controllers and Kubernetes.
• Kubernetes Sample Controller - Example of a Custom Resources with a Kubernetes Controller.
• Kubernetes Code Generator - The tooling that generated the Go libraries for the Custom Resource we define
• Kubernetes Controller Best Practices - Set of best practices written for writing Controllers inside Kubernetes. Also a great list for everywhere else too.
• Writing Kube Controllers for Everyone - Maciej Szulik, Red Hat - A great intro video into coding for Controllers, and explaining Informers and Listers.
• @markmandel regularly streams his development of Agones on Twitch. You can find the full archive on YouTube

Coding and Development

• How to write a good Git Commit message - Great way to make sure your Pull Requests get accepted.

• Log levels usage:

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

  More details can be found in this article.