Skip to content

Commit

Permalink
Improve contributing guide & docs (#1139)
Browse files Browse the repository at this point in the history 
* Improve root readme

* Add PR template

* Add new samples templates

* Update contributing guide

* Update contributing guide

* Update .github/CONTRIBUTING.md

Co-authored-by: Nim Jayawardena <[email protected]>

* Update contributing guide

* Update contributing guide

* Update contributing guide

---------

Co-authored-by: Nim Jayawardena <[email protected]>
  • Loading branch information
@bourgeoisor @NimJay
bourgeoisor and NimJay authored Feb 23, 2024
1 parent 07fef45 commit a1e433f
Show file tree
Hide file tree
Showing 6 changed files with 162 additions and 57 deletions.
108 changes: 57 additions & 51 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,65 +1,71 @@
# How to become a contributor and submit your own code
# How to contribute to kubernetes-engine-samples

## Contributor License Agreements

Before you're able to contribute to this repository, you need to sign a
Contributor License Agreement (CLA). You can follow the links below to
fill out the appropriate CLA (individual, or corporate):

* **[Individual
CLA](https://developers.google.com/open-source/cla/individual):** You are an individual writing original source code and own the intellectual property.
* **[Corporate
CLA](https://developers.google.com/open-source/cla/corporate):** You work for a company that allows you to contribute your work.

Follow either of the two links above to access the appropriate CLA and
instructions for how to sign and return it. Once we receive it, we'll be able to
accept your pull requests. You can visit <https://cla.developers.google.com/> to
confirm your current agreements or to sign a new one.

## Contributing a patch
## Steps to follow

1. [Submit an issue](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/issues/new) describing your proposed changes.
1. The repo owner will respond to your issue promptly. Once accepted:
1. Sign a Contributor License Agreement (see details above) if you haven't done so.
1. Fork the repo, develop and test your code changes.
1. Ensure that your code adheres to the existing style in the sample to which
you are contributing.
1. Ensure that your code has an appropriate set of unit tests which all pass.
1. Submit a pull request.

## Code reviews

All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.

## Community guidelines
1. Wait for the proposed changes to be accepted by a repo maintainer.
1. Sign a [Contributor License Agreement](#contributor-license-agreement-cla) if you haven't done so.
1. Fork the repo, develop, and test your code changes.
1. Ensure that your code follows [samples requirements](#samples-requirements).
1. Create a [pull request (PR)](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/compare).

This project follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
Note that:
- The PR reviewer may not be looking at the correctness of the code. They are
generally focusing on the PR structure and that it follows samples requirements.
- You are responsible for making prompt fixes to any issues arising with your samples. If a sample
goes out-of-date or breaks, it may be deprecated, depending on business needs.

## Samples requirements

All new code sample needs the following:
- An entry in the [CODEOWNERS file](/.github/CODEOWNERS), if applicable.
- A short `README.md` file with an external link pointing to the tutorial using the sample, if
applicable. There should only be one source of truth for sample instructions.
- A GitHub Action workflow that tests the sample code. At minimum, this should
dry-run any container image or Terraform configs and pass without any errors.
[[Example](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/.github/workflows/security-ci.yml)]
All new code samples require the following:
- **Directory** for all files of the sample (e.g. `/databases/mysql-on-gke/**`).
- Use one of the pre-existing top-level topic directories, if possible.
- **README file** with a link pointing to the tutorial or content using the sample.
[[Template](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/.github/new-samples-templates/README.md)]
- There should only be one source of truth for sample instructions (i.e. don't duplicate
instructions in the README that are or will be made available elsewhere).
- **GitHub Action workflow** that tests the sample code. At minimum, this should
dry-run any container images or Terraform scripts and pass without any errors.
[[Template](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/.github/new-samples-templates/workflow.yml)]
- Each container image should build successfully (e.g. `docker build...`).
- Each Terraform config should validate successfully (e.g. `terraform validate...`).
- If there are any other simple smoke tests that can be performed, they should also be added here.
- Each Terraform script should validate successfully (e.g. `terraform validate...`).
- If there are any other quick tests that can be performed, they should also be added here.
- **Dependencies** using up-to-date versions.
- Note that we have automation in place to update these versions on a weekly-basis.
- **License headers** on all source code and manifest files.
[[Example](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/.github/new-samples-templates/cloudbuild.yaml#L1-L13)]
- **Region tags** surrounding any file or snippets of code that will be embeded in a tutorial.
[[Example](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/ai-ml/llm-multiple-gpus/llm-service.yaml#L15-L28)]
- These surround code to be embeded and look like: `[START gke_topic_sample_title_file_name]` and
`[END gke_topic_sample_title_file_name]`.
- **CODEOWNERS file** with an entry listing the samples maintainers.
[[CODEOWNERS](/.github/CODEOWNERS)]

### Canonical container images
- If the sample relies on canonical image artifacts, these can be hosted officially, which requires:
- Cloud Build configs for all container images that pushes to the `google-samples` artifact registry.
[[Example](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/security/wi-secrets/cloudbuild.yaml)]
- A Terraform resource for the above Cloud Build configs.
- **Cloud Build configs** for all container images that pushes to the `google-samples` artifact registry.
[[Template](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/.github/new-samples-templates/cloudbuild.yaml)]
- **A Terraform resource** for the above Cloud Build configs.
[[Example](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/blob/main/.github/terraform/google-cloud-build-triggers.tf#L194-L207)]
- Note that in order for the Cloud Build configs to be applied to the
`google-samples` project, you need to run `terraform init && terraform apply`
while in that project (a repository admin will do this for you). [[docs](/.github/terraform/README.md)]
while in that project (a repository admin will do this for you). [[Docs](/.github/terraform/README.md)]
- The images will be of the form `us-docker.pkg.dev/google-samples/containers/gke<image_name>:latest`

If a pull request modifies any existing files in the `.github/terraform/` directory, these changes must be applied to the `google-samples` project
once the pull request is merged in. A repository admin will do this for you. [[docs](/.github/terraform/README.md)]
## Contributor License Agreement (CLA)

Before you're able to contribute to this repository, you need to sign a Contributor License Agreement (CLA).
You can follow the links below to fill out the appropriate CLA (individual, or corporate):

* **[Individual CLA](https://developers.google.com/open-source/cla/individual):**
You are an individual writing original source code and own the intellectual property.
* **[Corporate CLA](https://developers.google.com/open-source/cla/corporate):**
You work for a company that allows you to contribute your work.

Follow either of the two links above to access the appropriate CLA and instructions for how to sign and
return it. Once we receive it, we'll be able to accept your pull requests. You can visit
<https://cla.developers.google.com/> to confirm your current agreements or to sign a new one.

## Community guidelines

This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
7 changes: 7 additions & 0 deletions .github/new-samples-templates/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<!-- @TODO: replace all 3 placeholders -->

# <NAME_OF_SAMPLES>

This samples shows how to <ONE_LINE_DESCRIPTION>.

Visit https://cloud.google.com/kubernetes-engine/docs/<URL_TO_TUTORIAL> to follow the tutorial.
27 changes: 27 additions & 0 deletions .github/new-samples-templates/cloudbuild.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# @TODO: replace all 3 placeholders

steps:
- name: 'gcr.io/cloud-builders/docker'
args:
- 'build'
- '-t'
- 'us-docker.pkg.dev/google-samples/containers/gke/<CONTAINER_NAME>'
- '.'
dir: '<PATH/TO/SAMPLES>'

images:
- 'us-docker.pkg.dev/google-samples/containers/gke/<CONTAINER_NAME>'
46 changes: 46 additions & 0 deletions .github/new-samples-templates/workflow.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# @TODO: replace all placeholders
# @TODO: file name should be <category>-<sample-title>-ci.yml
# @TODO: see examples in the workflows/ directory for inspiration.)

name: <FILE_NAME>
on:
push:
branches:
- main
paths:
- '.github/workflows/<FILE_NAME>.yml'
- '<PATH/TO/SAMPLE>/**'
pull_request:
paths:
- '.github/workflows/<FILE_NAME>.yml'
- '<PATH/TO/SAMPLE>/**'
jobs:
job:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
# @TODO: Use a step like this to build container images
- name: Build container image
run: |
cd <PATH/TO/DOCKERFILE>
docker build --tag <CONTAINER_NAME> .
# @TODO: Use a step like this to validate Terraform scripts
- name: Validate Terraform config
run: |
cd <PATH/TO/TF>
terraform init
terraform validate
17 changes: 17 additions & 0 deletions .github/pull_request_template.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
## Description

<!-- Before creating this PR, make sure to thoroughly follow the contributing guide. -->
<!-- Add a description of the PR changes in this section. -->

REPLACE ME


## Tasks

<!-- Once the PR has been created, check boxes as appropriate. -->

* [ ] The [contributing guide](/.github/CONTRIBUTING.md) has been read and followed.
* [ ] The samples added / modified have been fully tested.
* [ ] Workflow files have been added / modified, if applicable.
* [ ] Region tags have been properly added, if new samples.
* [ ] All dependencies are set to up-to-date versions, as applicable.
14 changes: 8 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
# Kubernetes Engine Samples

[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/GoogleCloudPlatform/kubernetes-engine-samples&cloudshell_tutorial=README.md&cloudshell_workspace=hello-app)
# Google Kubernetes Engine (GKE) Samples

This repository contains sample applications used in
[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/) tutorials.

See the following resources to learn more:
See the following resources to get started:

- [Google Kubernetes Engine - Guides](https://cloud.google.com/kubernetes-engine/docs/concepts/kubernetes-engine-overview)
- [Google Kubernetes Engine - Quickstart](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster)

Or click on the following button to open the interactive quickstart demo:

[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/GoogleCloudPlatform/kubernetes-engine-samples&cloudshell_tutorial=README.md&cloudshell_workspace=quickstarts/hello-app)

## Contributing

* See [CONTRIBUTING.md](/.github/CONTRIBUTING.md)
* To learn how you can contribute new samples or fixes, see [the contributing guide](/.github/CONTRIBUTING.md).

## Licensing

* See [LICENSE](/LICENSE)
* This repository is licensed using an [Apache-2.0 license](/LICENSE).

0 comments on commit a1e433f

Please sign in to comment.