Skip to content

Commit

Permalink
docs(postprocessor): nudge users towards stable clients (#8513)
Browse files Browse the repository at this point in the history
Explicitly call out in our READMEs what a stable client is and recommend using it when available.

In a future PR I will cleanup readmes in batch.

Internal bug: 288889032
  • Loading branch information
codyoss authored Aug 30, 2023
1 parent 22e095a commit 05a1484
Showing 1 changed file with 11 additions and 0 deletions.
11 changes: 11 additions & 0 deletions internal/postprocessor/_README.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,17 @@ However, a `v1+` module may have breaking changes in two scenarios:
* Packages with `alpha` or `beta` in the import path
* The GoDoc has an explicit stability disclaimer (for example, for an experimental feature).

### Which package to use?

Generated client library surfaces can be found in packages who's import path
ends in `.../apivXXX`. The `XXX` could be something like `1` or `2` in the case
of a stable service backend or may be like `1beta2` or `2beta` in the case of a
more experimental service backend. Because of this fact, a given module can have
multiple clients for different service backends. In these cases it is generally
recommend to use clients with stable service backends, with import suffixes like
`apiv1`, unless you need to use features that are only present in a beta backend
or there is not yet a stable backend available.

## Google Cloud Samples

To browse ready to use code samples check [Google Cloud Samples](https://cloud.google.com/docs/samples?l=go).
Expand Down

0 comments on commit 05a1484

Please sign in to comment.