agones.dev/agones@v1.53.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  ## Submitting code via Pull Requests
    23  
    24  *Thank you* for considering submitting code to Agones!
    25  
    26  - We follow the [GitHub Pull Request Model](https://help.github.com/articles/about-pull-requests/) for
    27    all contributions.
    28  - For large bodies of work, we recommend creating an issue and labelling it
    29    "[kind/design](https://github.com/googleprivate/agones/issues?q=is%3Aissue+is%3Aopen+label%3Akind%2Fdesign)"
    30    outlining the feature that you wish to build, and describing how it will be implemented. This gives a chance
    31    for review to happen early, and ensures no wasted effort occurs.
    32  - For new features, documentation *must* be included. Review the [Documentation Editing and Contribution](https://agones.dev/site/docs/contribute/)
    33    guide for details.
    34  - It is strongly recommended that new API design follows the [Google AIPs](https://google.aip.dev/) design guidelines.  
    35  - All submissions, including submissions by project members, will require review before being merged.
    36  - Once review has occurred, please rebase your PR down to a single commit. This will ensure a nice clean Git history.
    37  - 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).
    38  - Please follow the code formatting instructions below.
    39  
    40  ### Additional Instructions for Unreal Plugin Pull Requests
    41  
    42  As there is no CI for the Unreal plugin, the following checklist should be run
    43  manually before the PR is approved, using the latest released version of UE4.
    44  
    45  1. Create default C++ template project in UE4.
    46  1. Create a Plugins folder under the project directory (should be a sibling of the .uproject file).
    47  1. Copy the [sdks/unreal/Agones](sdks/unreal/Agones) directory into the Plugins folder.
    48  1. Build the UE4 project.
    49  1. If the build succeeded, paste the build logs into the PR.
    50  
    51  ## Formatting
    52  
    53  When submitting pull requests, make sure to do the following:
    54  
    55  - Format all Go code with [gofmt](https://golang.org/cmd/gofmt/). Many people
    56    use [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) which
    57    fixes import statements and formats code in the same style of `gofmt`.
    58  - C++ code should follow the [Google C++ Style
    59    Guide](https://google.github.io/styleguide/cppguide.html), which can be
    60    applied automatically using the
    61    [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) command-line tool
    62    (e.g., `clang-format -style=Google foo.cc`). The exception to this is
    63    the [Unreal Engine plugin code](sdks/unreal/Agones), which should follow the
    64    [Unreal Engine 4 Coding Standard](https://docs.unrealengine.com/en-US/Programming/Development/CodingStandard/index.html).
    65  - Remove trailing whitespace. Many editors will do this automatically.
    66  - Ensure any new files have [a trailing newline](https://stackoverflow.com/questions/5813311/no-newline-at-end-of-file)
    67  
    68  ## Feature Stages
    69  
    70  Often, new features will need to go through experimental stages so that we can gather feedback and adjust as necessary.
    71  
    72  You can see this project's [feature stage documentation](https://agones.dev/site/docs/guides/feature-stages/) on the Agones
    73  website.
    74  
    75  If you are working on a new feature, you may need to take feature stages into account. This should be discussed on a
    76   design ticket prior to commencement of work. 
    77  
    78  ## Continuous Integration
    79  
    80  Continuous integration is provided by [Google Cloud Container Builder](https://cloud.google.com/container-builder/),
    81  through the [cloudbuilder.yaml](./cloudbuild.yaml) file found at the root of the directory.
    82  
    83  Build success/failure with relevant details are pushed automatically to pull requests via [agones-bot](./build/agones-bot/README.md).
    84  
    85  See the [Container Builder documentation](https://cloud.google.com/container-builder/docs/) for more details on
    86  how to edit and expand the build process.
    87  
    88  ## Kubernetes Versions Update
    89  ### When to update supported Kubernetes Versions
    90  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.
    91  ### How to update supported Kubernetes Versions
    92  Please follow the steps below to update the Kubernetes versions supported.
    93  
    94  1. Create a Issue from the [kubernetes update issue template](./.github/ISSUE_TEMPLATE/kubernetes_update.md) with the newly supported versions.
    95  2. Complete all items in the issue checklist.
    96  3. Close the issue.
    97  
    98  
    99  ## Community Meetings
   100  
   101  Community meetings occur every month, and are open to all who wish to attend!
   102  
   103  You can see them on our calendar 
   104  ([web](https://calendar.google.com/calendar/embed?src=google.com_828n8f18hfbtrs4vu4h1sks218%40group.calendar.google.com&ctz=America%2FLos_Angeles), 
   105  [ical](https://calendar.google.com/calendar/ical/google.com_828n8f18hfbtrs4vu4h1sks218%40group.calendar.google.com/public/basic.ics)) and/or join the 
   106  [mailing list or Slack](https://agones.dev/site/community/)
   107  for notifications.
   108  
   109  ## Becoming a Collaborator on Agones
   110  
   111  If you have submitted at least one Pull Request and had it merged, you may wish to become an official collaborator.
   112  This will give you the ability to have tickets assigned to you (or you can assign tickets to yourself!).
   113  
   114  We have a [community membership guide](./docs/governance/community_membership.md), that outlines the process.
   115  
   116  ## Becoming an Approver on Agones
   117  
   118  If you are interested in becoming an Approver on the Agones project and getting commit access to the
   119  repository, we have a [community membership guide](./docs/governance/community_membership.md), that outlines the process.
   120  
   121  ### Additional Resources
   122  
   123  #### Extending Kubernetes
   124  
   125  - [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/api-extension/custom-resources/) -
   126    This is how we define our own resource names (`GameServer`, etc) within Kubernetes.
   127  - [Kubernetes Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) -
   128    Kubernetes documentation on writing controllers.
   129  - [Extend the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/) -
   130    This page shows how to install a custom resource into the Kubernetes API by creating a CustomResourceDefinition.
   131  - [Joe Beda's TGIK Controller](https://github.com/jbeda/tgik-controller) -
   132    [Joe Beda](https://twitter.com/jbeda) did a video series on writing controllers for Kubernetes.
   133    **This is the best resource for learning about controllers and Kubernetes.**
   134  - [Kubernetes Sample Controller](https://github.com/kubernetes/sample-controller) -
   135    Example of a Custom Resources with a Kubernetes Controller.
   136  - [Kubernetes Code Generator](https://github.com/kubernetes/code-generator) -
   137    The tooling that generated the Go libraries for the Custom Resource we define
   138  - [Kubernetes Controller Best Practices](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/controllers.md) -
   139    Set of best practices written for writing Controllers inside Kubernetes. Also a great list for everywhere else too.
   140  - [Writing Kube Controllers for Everyone - Maciej Szulik, Red Hat](https://www.youtube.com/watch?v=AUNPLQVxvmw) -
   141    A great intro video into coding for Controllers, and explaining Informers and Listers.
   142  - [@markmandel](https://github.com/markmandel) regularly streams his development of Agones on [Twitch](https://www.twitch.tv/markmandel).
   143    You can find the full archive on [YouTube](https://www.youtube.com/playlist?list=PLqqp1QEhKwa5aNivDIE4SS21ehE9Zt0VZ)
   144  
   145  
   146  #### Coding and Development
   147  
   148  - [How to write a good Git Commit message](https://chris.beams.io/posts/git-commit/) -
   149    Great way to make sure your Pull Requests get accepted.
   150  - **Log levels usage:**
   151    - 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.
   152    - 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.
   153    - 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.
   154    - 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.
   155    - 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.
   156  
   157    More details can be found in [this article](https://medium.com/@tom.hombergs/tip-use-logging-levels-consistently-913b7b8e9782).