Documentation on supporting new services #923

ajkannan · 2016-04-14T16:21:54Z

Fixes #819

coveralls · 2016-04-14T16:32:23Z

Coverage remained the same at 85.571% when pulling 67e3f08 on ajkannan:new-client-library-docs into 13ab36f on GoogleCloudPlatform:master.

ajkannan · 2016-04-14T16:32:46Z

/cc @mderka since you're newest to the project and have recently created a client library.

ADDING_NEW_CLIENTS.md

+
+Before starting work on the API layer, write a design document and provide sample API code, either in the design document or as a pull request tagged with the "don't merge" label.  As part of the design process, be sure to examine the Google Cloud service API and any implementations provided in other gcloud-* language libraries.  Solicit feedback from other contributors to the repository.
+
+When possible, make classes immutable, providing builders when necessary.  Commonly-used classes that contain metadata should also contain a subclass that provides functions on that metadata.  For example, see `BlobInfo` (the metadata class) and `Blob` (the functional class).  The builders for both objects should implement a common interface or abstract class, and the subclass should delegate to the metadata class builder.  Make model object classes serializable.  Also, make classes final when possible, except when the class contains functionality that cannot be fully tested by users without mocking the object.


coveralls · 2016-04-14T21:49:08Z

Coverage remained the same at 85.571% when pulling 573c07e on ajkannan:new-client-library-docs into 13ab36f on GoogleCloudPlatform:master.

ADDING_NEW_CLIENTS.md

+
+#### API layer
+
+Before starting work on the API layer, write a design document and provide sample API code, either in the design document or as a pull request tagged with the "don't merge" label.  As part of the design process, be sure to examine the Google Cloud service API and any implementations provided in other gcloud-* language libraries.  Solicit feedback from other contributors to the repository.  Client libraries should be low-level while minimizing boilerplate code needed by API users.  The library should also be flexible enough to be used by higher-level libraries.  For example, Objectify should be able to use `gcloud-java-datastore`.


ADDING_NEW_CLIENTS.md

+
+#### Tests
+
+API-level functionality should be well-covered by unit tests.  Coders and reviewers should examine test coverage to ensure that important code paths are not being left untested.  As of now, `gcloud-java` relies on integration tests to test the SPI layer.  Unit tests for the API layer should be located in the package `com.google.cloud.servicename`.  Integration tests should be placed in a separate package, `com.google.cloud.servicename.it`, which enables us to catch method access bugs.  Unit tests for the test helper should be placed in the package `com.google.cloud.servicename.testing`.  All unit tests run for pull requests, but integration tests are only run upon merging the pull request.  We only run integration tests upon merging pull requests to avoid decrypting and exposing credentials to anybody who can create a pull request from a fork.


coveralls · 2016-04-14T22:08:02Z

Coverage increased (+0.01%) to 85.581% when pulling d9c83f6 on ajkannan:new-client-library-docs into 13ab36f on GoogleCloudPlatform:master.

ADDING_NEW_CLIENTS.md

@@ -73,21 +88,20 @@ Notes/reminders:

 ### Workflow

-New services should be created in a branch based on `master`.  The branch name should include "alpha".  For example, while developing `gcloud-java-pubsub`, all Pub/Sub related work should be done in `pubsub-alpha`.  All code should be submitted through pull requests from a branch on a forked repository.  Limiting pull request size is very helpful for reviewers.  All code that is merged into the branch should be standalone and well-tested.  Any todo comments in the code should have an associated Github issue number for tracking purposes.  You should periodically pull updates from the master branch, especially if there are project-wide updates or if relevant changes have been made to the core utilities library, `gcloud-java-core`.
+New services should be created in a branch based on `master`.  The branch name should include the suffix "-alpha".  For example, while developing `gcloud-java-pubsub`, all Pub/Sub related work should be done in `pubsub-alpha`.  All code should be submitted through pull requests from a branch on a forked repository.  Limiting pull request size is very helpful for reviewers.  All code that is merged into the branch should be standalone and well-tested.  Any todo comments in the code should have an associated Github issue number for tracking purposes.  You should periodically pull updates from the master branch, especially if there are project-wide updates or if relevant changes have been made to the core utilities library, `gcloud-java-core`.


mderka · 2016-04-14T22:17:41Z

Very nice. I am done.

ajkannan · 2016-04-14T23:00:01Z

Thanks @mderka! I pushed a commit with the changes.

CONTRIBUTING.md

-See [ADDING_NEW_CLIENTS](./ADDING_NEW_CLIENTS.md) for guidelines on how to add a new client library to `gcloud-java`.
+Adding Support for a New Service
+--------------------------------
+See [SUPPORTING_NEW_SERVICES](./SUPPORT_NEW_SERVICES.md) for guidelines on how to add a new client library to `gcloud-java`.


coveralls · 2016-04-14T23:04:37Z

Coverage decreased (-0.004%) to 85.567% when pulling d4d4d5b on ajkannan:new-client-library-docs into 13ab36f on GoogleCloudPlatform:master.

SUPPORTING_NEW_SERVICES.md

+
+### Workflow
+
+New services should be created in a branch based on `master`.  The branch name should include the suffix "-alpha".  For example, while developing `gcloud-java-pubsub`, all Pub/Sub related work should be done in `pubsub-alpha`.  All code should be submitted through pull requests from a branch on a forked repository.  Limiting pull request size is very helpful for reviewers.  All code that is merged into the branch should be standalone and well-tested.  Any todo comments in the code should have an associated Github issue number for tracking purposes.  You should periodically pull updates from the master branch, especially if there are project-wide updates or if relevant changes have been made to the core utilities library, `gcloud-java-core`.


aozarov · 2016-04-15T03:33:27Z

I am done with my review. Looks really good, thanks for doing that!

ajkannan · 2016-04-15T21:24:31Z

All comments incorporated, ready for another pass.

coveralls · 2016-04-15T21:35:59Z

Coverage remained the same at 85.567% when pulling 666c3d4 on ajkannan:new-client-library-docs into 527c656 on GoogleCloudPlatform:master.

coveralls · 2016-04-15T21:41:04Z

Coverage remained the same at 85.567% when pulling 666c3d4 on ajkannan:new-client-library-docs into 527c656 on GoogleCloudPlatform:master.

aozarov · 2016-04-15T21:58:16Z

Looks great. Feel free to squash and merge.

…o v2.1.2 (#923) [![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [com.google.cloud:google-cloud-vision](https://togithub.com/googleapis/java-vision) | `2.1.1` -> `2.1.2` | [![age](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-vision/2.1.2/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-vision/2.1.2/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-vision/2.1.2/compatibility-slim/2.1.1)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-vision/2.1.2/confidence-slim/2.1.1)](https://docs.renovatebot.com/merge-confidence/) | --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Renovate will not automatically rebase this PR, because other commits have been found. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. ⚠ **Warning**: custom changes will be lost. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-vision).

…923) [![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [com.google.cloud:google-cloud-core](https://togithub.com/googleapis/java-core) | `2.8.0` -> `2.8.1` | [![age](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-core/2.8.1/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-core/2.8.1/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-core/2.8.1/compatibility-slim/2.8.0)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-core/2.8.1/confidence-slim/2.8.0)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>googleapis/java-core</summary> ### [`v2.8.1`](https://togithub.com/googleapis/java-core/blob/HEAD/CHANGELOG.md#281-httpsgithubcomgoogleapisjava-corecomparev280v281-2022-06-27) [Compare Source](https://togithub.com/googleapis/java-core/compare/v2.8.0...v2.8.1) ##### Dependencies - update dependency com.google.protobuf:protobuf-bom to v3.21.2 ([#851](https://togithub.com/googleapis/java-core/issues/851)) ([c0f09f0](https://togithub.com/googleapis/java-core/commit/c0f09f0fcd57a2d90e0a99b17c9e346df8651d65)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-video-intelligence).

🤖 I have created a release *beep* *boop* --- ## [2.2.1](googleapis/java-video-intelligence@v2.2.0...v2.2.1) (2022-07-01) ### Dependencies * update dependency com.google.cloud:google-cloud-core to v2.8.1 ([#923](googleapis/java-video-intelligence#923)) ([af680c9](googleapis/java-video-intelligence@af680c9)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- ### Updating meta-information for bleeding-edge SNAPSHOT release. --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

…-plugin to v3.4.1 (#923) [![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [org.apache.maven.plugins:maven-javadoc-plugin](https://maven.apache.org/plugins/) | `3.4.0` -> `3.4.1` | [![age](https://badges.renovateapi.com/packages/maven/org.apache.maven.plugins:maven-javadoc-plugin/3.4.1/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/org.apache.maven.plugins:maven-javadoc-plugin/3.4.1/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/org.apache.maven.plugins:maven-javadoc-plugin/3.4.1/compatibility-slim/3.4.0)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/org.apache.maven.plugins:maven-javadoc-plugin/3.4.1/confidence-slim/3.4.0)](https://docs.renovatebot.com/merge-confidence/) | --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Renovate will not automatically rebase this PR, because other commits have been found. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. ⚠ **Warning**: custom changes will be lost. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-containeranalysis).

…orting to v0.124.3-beta (#923) * chore(deps): update dependency com.google.cloud:google-cloud-errorreporting to v0.124.3-beta * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- ## [3.4.3](googleapis/java-monitoring@v3.4.2...v3.4.3) (2022-09-09) ### Dependencies * Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.2 ([#922](googleapis/java-monitoring#922)) ([9457c57](googleapis/java-monitoring@9457c57)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [google-cloud-storage](https://togithub.com/googleapis/python-storage) | `==2.0.0` -> `==2.5.0` | [![age](https://badges.renovateapi.com/packages/pypi/google-cloud-storage/2.5.0/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/pypi/google-cloud-storage/2.5.0/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/pypi/google-cloud-storage/2.5.0/compatibility-slim/2.0.0)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/pypi/google-cloud-storage/2.5.0/confidence-slim/2.0.0)](https://docs.renovatebot.com/merge-confidence/) | --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Renovate will not automatically rebase this PR, because other commits have been found. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. ⚠ **Warning**: custom changes will be lost. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-language).

🤖 I have created a release *beep* *boop* --- ### Updating meta-information for bleeding-edge SNAPSHOT release. --- This PR was generated with [Release Please](https://togithub.com/googleapis/release-please). See [documentation](https://togithub.com/googleapis/release-please#release-please).

🤖 I have created a release *beep* *boop* --- ### Updating meta-information for bleeding-edge SNAPSHOT release. --- This PR was generated with [Release Please](https://togithub.com/googleapis/release-please). See [documentation](https://togithub.com/googleapis/release-please#release-please).

🤖 I have created a release *beep* *boop* --- ## [2.8.14](googleapis/java-core@v2.8.13...v2.8.14) (2022-09-20) ### Dependencies * Update dependency com.google.api.grpc:proto-google-common-protos to v2.9.3 ([#922](googleapis/java-core#922)) ([61ada00](googleapis/java-core@61ada00)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

Documentation on how to add a new client library

67e3f08

ajkannan added the docs label Apr 14, 2016

googlebot added the cla: yes This human has signed the Contributor License Agreement. label Apr 14, 2016

mziccard reviewed Apr 14, 2016
View reviewed changes

mderka reviewed Apr 14, 2016
View reviewed changes

Add more gcloud-java-core concepts + fixes for comments

d9c83f6

ajkannan force-pushed the new-client-library-docs branch from 573c07e to d9c83f6 Compare April 14, 2016 22:02

mderka reviewed Apr 14, 2016
View reviewed changes

Rename doc + address comments

d4d4d5b

ajkannan reviewed Apr 14, 2016
View reviewed changes

ajkannan changed the title ~~Documentation on how to add a new client library~~ Documentation on supporting new services Apr 14, 2016

aozarov reviewed Apr 15, 2016
View reviewed changes

Incorporate feedback

666c3d4

ajkannan force-pushed the new-client-library-docs branch from 0cba776 to 666c3d4 Compare April 15, 2016 21:23

fixes

7cefdfe

ajkannan merged commit 8b766e6 into googleapis:master Apr 15, 2016

ajkannan deleted the new-client-library-docs branch April 15, 2016 22:07

github-actions bot pushed a commit that referenced this pull request Jul 14, 2022

chore(main): release 3.6.0 (#923)

3c28e59

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

suztomo pushed a commit that referenced this pull request Feb 1, 2023

deps: update iam.version to v1.6.16 (#923)

d737e17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation on supporting new services #923

Documentation on supporting new services #923

ajkannan commented Apr 14, 2016

coveralls commented Apr 14, 2016

ajkannan commented Apr 14, 2016

This comment was marked as spam.

coveralls commented Apr 14, 2016

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

coveralls commented Apr 14, 2016

This comment was marked as spam.

This comment was marked as spam.

mderka commented Apr 14, 2016

ajkannan commented Apr 14, 2016

This comment was marked as spam.

coveralls commented Apr 14, 2016

This comment was marked as spam.

aozarov commented Apr 15, 2016

ajkannan commented Apr 15, 2016

coveralls commented Apr 15, 2016

coveralls commented Apr 15, 2016

aozarov commented Apr 15, 2016


		Before starting work on the API layer, write a design document and provide sample API code, either in the design document or as a pull request tagged with the "don't merge" label. As part of the design process, be sure to examine the Google Cloud service API and any implementations provided in other gcloud-* language libraries. Solicit feedback from other contributors to the repository.

		When possible, make classes immutable, providing builders when necessary. Commonly-used classes that contain metadata should also contain a subclass that provides functions on that metadata. For example, see `BlobInfo` (the metadata class) and `Blob` (the functional class). The builders for both objects should implement a common interface or abstract class, and the subclass should delegate to the metadata class builder. Make model object classes serializable. Also, make classes final when possible, except when the class contains functionality that cannot be fully tested by users without mocking the object.


		#### API layer

		Before starting work on the API layer, write a design document and provide sample API code, either in the design document or as a pull request tagged with the "don't merge" label. As part of the design process, be sure to examine the Google Cloud service API and any implementations provided in other gcloud-* language libraries. Solicit feedback from other contributors to the repository. Client libraries should be low-level while minimizing boilerplate code needed by API users. The library should also be flexible enough to be used by higher-level libraries. For example, Objectify should be able to use `gcloud-java-datastore`.


		#### Tests

		API-level functionality should be well-covered by unit tests. Coders and reviewers should examine test coverage to ensure that important code paths are not being left untested. As of now, `gcloud-java` relies on integration tests to test the SPI layer. Unit tests for the API layer should be located in the package `com.google.cloud.servicename`. Integration tests should be placed in a separate package, `com.google.cloud.servicename.it`, which enables us to catch method access bugs. Unit tests for the test helper should be placed in the package `com.google.cloud.servicename.testing`. All unit tests run for pull requests, but integration tests are only run upon merging the pull request. We only run integration tests upon merging pull requests to avoid decrypting and exposing credentials to anybody who can create a pull request from a fork.


		### Workflow

		New services should be created in a branch based on `master`. The branch name should include the suffix "-alpha". For example, while developing `gcloud-java-pubsub`, all Pub/Sub related work should be done in `pubsub-alpha`. All code should be submitted through pull requests from a branch on a forked repository. Limiting pull request size is very helpful for reviewers. All code that is merged into the branch should be standalone and well-tested. Any todo comments in the code should have an associated Github issue number for tracking purposes. You should periodically pull updates from the master branch, especially if there are project-wide updates or if relevant changes have been made to the core utilities library, `gcloud-java-core`.

Documentation on supporting new services #923

Documentation on supporting new services #923

Conversation

ajkannan commented Apr 14, 2016

coveralls commented Apr 14, 2016

ajkannan commented Apr 14, 2016

This comment was marked as spam.

coveralls commented Apr 14, 2016

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

coveralls commented Apr 14, 2016

This comment was marked as spam.

This comment was marked as spam.

mderka commented Apr 14, 2016

ajkannan commented Apr 14, 2016

This comment was marked as spam.

coveralls commented Apr 14, 2016

This comment was marked as spam.

aozarov commented Apr 15, 2016

ajkannan commented Apr 15, 2016

coveralls commented Apr 15, 2016

coveralls commented Apr 15, 2016

aozarov commented Apr 15, 2016