GoogleCloudPlatform / GoogleCloudPlatform/samples-style-guide

Proposal: Product-specific guidelines

Open
#118 1 comment 0 reactions 0 assignees View on GitHub
guideline: needs work type: feature request
Dominant language
HTML
Stars
13
Forks
17
PR merge metrics
No merged PRs in 30d

Description

### Description

Either in the existing page or a new page, add product or PA-specific guidelines. This would be a central place anyone can visit to see Sample expectations that are specific to a product. This provides a path for some sample consistency within a product space even with high turnover of contributors that have limited knowledge transfer.

I imagine a section of product guidelines where individual products are H2 headings and guidelines per product are H3 headings.

Using Eventarc as an example:

* **Building Container Images:** [Simplicity] Prefer jib or buildpacks to build container images, eventarc samples shouldn't teach containerization. (Note: This could be promoted to a general default sample guideline)
* **CloudEvent Metadata Priority:** [Idiomaticity] Prefer CloudEvent metadata over payload fields where redundant values can serve the same purpose. For example, CloudEvent time over data timestamps if the specific time of the resource update is not required
* **Building Test Cases for Integration Tests:** [Maintainability] Prefer using CloudEvents SDK to build events for integration testing. This may not be feasible in all languages.
* **Inline Type Definitions:** [Clarity] Languages without a type library should include an inline object definition with well-commented, minimal fields. The type should link to the proto and JSON-schema definition, either directly to the GitHub resource or via Cloud Docs.

### Impact

Reduced design/planning overhead, increased consistency. Individual guidelines could create new work and should still go through a review process.

### Challenge

Choosing whether to place product guidelines in the main guide page or a new page.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.