Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: update links in contrib guide (#2903)
- Loading branch information
1 parent
85b5047
commit eee3707
Showing
1 changed file
with
36 additions
and
189 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |