From eee3707d1955ca479c526e5be201b0cb6b5eabb4 Mon Sep 17 00:00:00 2001
From: Justin Beckwith <justin.beckwith@gmail.com>
Date: Thu, 14 Feb 2019 08:47:40 -0800
Subject: [PATCH] docs: update links in contrib guide (#2903)

---
 CONTRIBUTING.md | 225 ++++++++----------------------------------------
 1 file changed, 36 insertions(+), 189 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 06e577ab3b3..78aaa61b269 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,208 +1,55 @@
-# Contributing
+# How to become a contributor and submit your own code
 
-1. **Please sign one of the contributor license agreements below.**
-2. Fork the repo, develop and test your code changes.
-3. Add your (or your organization's) name to the AUTHORS and CONTRIBUTORS files.
-4. Send a pull request.
+**Table of contents**
 
-## Testing
-
-### Setup
-
-### Unit Tests
-
-After running `npm install` from the root of the repository, start the unit tests:
-
-```sh
-$ npm test
-```
-
-If you're only concerned with one module, you can cd into its directory, and run the same command there:
-
-```sh
-$ cd packages/storage
-$ npm test
-```
-
-### Documentation (Snippet) Tests
-
-All of the public methods across our APIs have an `@example` block that shows how the method is intended to be used. These snippets can be smoke-tested for accuracy:
-
-```sh
-$ npm run snippet-test
-```
-
-Note that this command is included as part of the root directory's `npm test`, but is not run if you are only working in a single module's directory.
-
-
-### System Tests
-
-To run the system tests, first create and configure a project in the Google Developers Console following the [instructions on how to run google-cloud-node][elsewhere]. After that, set the following environment variables:
-
-- **GCLOUD_TESTS_PROJECT_ID**: Developers Console project's ID (e.g. bamboo-shift-455)
-- ***GCLOUD_TESTS_PROJECT_NUMBER*** (*optional*): Developers Console project number (e.g. 1046198160504).
-- **GCLOUD_TESTS_KEY**: The path to the JSON key file.
-- ***GCLOUD_TESTS_API_KEY*** (*optional*): An API key.
-- ***GCLOUD_TESTS_DNS_DOMAIN*** (*optional*): A domain you own managed by Cloud DNS (expected format: `'gcloud-node.com.'`).
-
-Install the [gcloud command-line tool][gcloudcli] to your machine and use it to create the indexes used in the datastore system tests with indexes found in `system-test/data/index/yaml`:
-
-From the project's root directory:
-
-```sh
-# Install the app component
-$ gcloud components update app
-
-# Set the default project in your env
-$ gcloud config set project $GCLOUD_TESTS_PROJECT_ID
-
-# Authenticate the gcloud tool with your account
-$ gcloud auth login
-
-# Create the indexes
-$ gcloud preview datastore create-indexes system-test/data/index.yaml
-```
-
-You may now run the system tests:
-
-```sh
-$ npm run system-test
-```
-
-### Test Coverage
-
-Generate the coverage report:
-
-```sh
-$ npm run cover
-```
-
-The test coverage report will be available in `.coverage/`.
+* [Contributor License Agreements](#contributor-license-agreements)
+* [Contributing a patch](#contributing-a-patch)
+* [Running the tests](#running-the-tests)
+* [Releasing the library](#releasing-the-library)
 
 ## Contributor License Agreements
 
-Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):
-
-- **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need to sign an [individual CLA][indvcla].
-- **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a [corporate CLA][corpcla].
-
-You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.
-
-# Maintainer Guides
-
-## Publishing
-
-To publish this module, you must be signed into an npm account that is part of the `google-cloud` organization.
-
-```sh
-# If publishing a service module:
-#   $ cd packages/bigquery
-# Otherwise stay in the root directory
-
-$ npm run publish-module {{version}}
-```
-
-  - **version** In the format of `0.2.0` or an npm-recognized alias: "major", "minor", or "patch"
-
-This will:
-
-  1. Copy the necessary legal files into the working directory so they are included with the release
-  1. Publish the module
-  1. Create a commit and tag for the new version
-
-The output from the command will remind you to push to master with a command like the following:
-
-```sh
-$ git push origin master --follow-tags
-```
-
-### Release Notes
-
-If you're thinking "this library needs a schwifty, CI-driven, changelog-generator supertool", hold the phone. It's important to make our library as human as possible. So, please, take a few minutes and pretend that you're the user. What would you want to see?
-
-  1. [Draft a new release](https://github.com/GoogleCloudPlatform/google-cloud-node/releases/new)
-  1. Use the following template as a starting point. Remove sections that aren't relevant. Feel free to make improvements.
-
-  - **Tag version** Match to the release version.
-  - **Release title**
-    - `google-cloud` releases: `v0.39.0`
-    - `@google-cloud/module` releases: `@google-cloud/module v0.2.0`
-
-<pre>
-### :warning: Breaking Changes
-#### We use promises now!
-Issue: #ISSUE_NUMBER
-PR: #PR_NUMBER
-
-Take a few sentences (minimum) to talk to the user. Remember that this change might require a lot of their time, so make sure to explain why it's worth it.
-
-##### Before
-```js
-bucket.getFiles(function(err, files) {
-  if (err) {
-    // An API error occurred.
-  }
-
-  // `files` is an array of `File` objects.
-});
-```
-
-##### After
-```js
-bucket.getFiles()
-  .then(function(files) {
-    // `files` is an array of `File` objects.
-  }, function(err) {
-    // An API error occurred.
-  });
-```
-
-#### Features
-
-- (#ISSUE_NUMBER, #PR_NUMBER): Describe the new state of the code, i.e. "vision.annotate() now accepts Buffers."
+We'd love to accept your sample apps and patches! Before we can take them, we
+have to jump a couple of legal hurdles.
 
-#### Fixes
+Please fill out either the individual or corporate Contributor License Agreement
+(CLA).
 
-- (#ISSUE_NUMBER, #PR_NUMBER): Describe the new state of the code, i.e. "vision.detect() properly handles multiple images."
-</pre>
+  * If you are an individual writing original source code and you're sure you
+    own the intellectual property, then you'll need to sign an [individual CLA](https://developers.google.com/open-source/cla/individual).
+  * If you work for a company that wants to allow you to contribute your work,
+    then you'll need to sign a [corporate CLA](https://developers.google.com/open-source/cla/corporate).
 
-Checklist:
+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.
 
-  - [ ] I checked that all links work
-  - [ ] I removed any sections that weren't relevant (e.g., if there weren't any "Fixes" in this release, remove the heading entirely)
-  - [ ] I made sure all breaking changes are noted
-  - [x] Never stop saying "schwifty"
+## Contributing A Patch
 
-### Updating Documentation
+1.  Submit an issue describing your proposed change to the repo in question.
+1.  The repo owner will respond to your issue promptly.
+1.  If your proposed change is accepted, and you haven't already done so, sign a
+    Contributor License Agreement (see details above).
+1.  Fork the desired repo, develop and test your code changes.
+1.  Ensure that your code adheres to the existing style in the code to which
+    you are contributing.
+1.  Ensure that your code has an appropriate set of tests which all pass.
+1.  Submit a pull request.
 
-All of the documentation is powered by JSDoc, we parse it into JSON and feed it to an [application](https://github.com/GoogleCloudPlatform/gcloud-common/tree/master/site) built in Angular. Hopefully our CI builds and updates the documentation for each successful merge to master, but if for whatever reason a manual update is required please refer to the following steps.
+## Running the tests
 
-We can build the documentation using the `npm run prepare-ghpages` command. This command optionally accepts two parameters.
+1.  [Prepare your environment for Node.js setup][setup].
 
-* module - The name of the module to build (e.g. `google-cloud`).
-* version - The target version of the module. (e.g. `0.43.0`) Defaults to master.
+1.  Install dependencies:
 
-If both parameters are omitted, we will build the master docs for all modules.
+        npm install
 
-```sh
-$ npm run prepare-ghpages google-cloud 0.43.0
-```
+1.  Run the tests:
 
-Now it's time to push the docs! If you wish to preview locally you can optionally run an http server in the `gh-pages` folder.
+        npm test
 
-```sh
-$ cd gh-pages
-$ http-server . # Run the server to look for any visual errors
-$ git push origin gh-pages
-$ cd ..
-```
-Finally the last thing to do is cleanup the submodule we created to copy over the JSON.
+1.  Lint (and maybe fix) any changes:
 
-```sh
-$ npm run remove-ghpages
-```
+        npm run fix
 
-[elsewhere]: ../README.md#elsewhere
-[gcloudcli]: https://developers.google.com/cloud/sdk/gcloud/
-[indvcla]: https://developers.google.com/open-source/cla/individual
-[corpcla]: https://developers.google.com/open-source/cla/corporate
+[setup]: https://cloud.google.com/nodejs/docs/setup