Skip to content

Latest commit

 

History

History
66 lines (37 loc) · 3.34 KB

CONTRIBUTING.md

File metadata and controls

66 lines (37 loc) · 3.34 KB

How to become a contributor and submit your own code

This repository contains samples that the documentation on Google Cloud Platform references. Samples for a client library should be added to the client repository, not this repository. (For example, the functions folder is reserved for samples used in cloud.google.com/functions). If you wrote a great sample but it is not used in Google's official documentation, there are better suited places to publish it such as a community tutorial.

Run the tests for a single sample

  1. Obtain authentication credentials. Depending on the sample, you need to enable the appropriate APIs in the Cloud Console.

     gcloud auth application-default login

  2. Change directory to one of the sample folders, e.g. datastore.

     cd datastore/

  3. Install the dependencies.

     npm install

  4. Run the tests.

     npm test

Adding new samples

All samples must have tests. We use mocha as testing framework. The package.json file within your sample directory must contain a test script that executes the mocha tests via npm test (example).

For new samples, a GitHub Actions workflow should be created to run your tests on the CI system:

  1. Add an entry to .github/workflows/workflows.json matching the directory with your sample code.

  2. From the root of the repo, generate a new workflow in the workflows directory. You can specify a path to only generate the specific workflow, e.g. cloud-tasks. If the path is omitted, all workflows will be generated.

     node .github/workflows/generate.js [path]

Note There are some existing samples that use an alternative CI system. It is recommended to use GitHub Actions for new samples, but these instructions are provided below for your reference.

Add a build configuration file (.cfg) for your samples in .kokoro/. Check existing config files for the right format.

All tests need a corresponding job file outside of GitHub. If you are a Googler, please provide the CL alongside your PR. See the internal codelab for Kokoro for details. If you don't work at Google, the person reviewing your PR will create the job config for you.

Style

The Google Cloud Samples Style Guide is considered the primary guidelines for all Google Cloud samples.

Samples in this repository also follow the JavaScript coding standards. See instructions below to run the linter to match our JavaScript coding standards:

  1. Install dependencies at the root of the nodejs-docs-samples directory.

     npm install

  2. Run the linter for all samples, including the ones you're adding.

     npm run lint

Failing CI

Required tests need to pass. Tests that are not required are expected to fail, they are usually work in progress.