docs: Document job management and interactive API protos#39294
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #39294 +/- ##
============================================
- Coverage 58.73% 58.70% -0.03%
Complexity 7418 7418
============================================
Files 1649 1649
Lines 212369 212787 +418
Branches 6330 6330
============================================
+ Hits 124727 124925 +198
- Misses 83095 83315 +220
Partials 4547 4547
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Add documentation comments to previously undocumented messages and fields in the Beam job management and interactive API protos: beam_artifact_api.proto: ArtifactRetrievalService, ArtifactStagingService, ArtifactRequestWrapper, ProxyManifest, PutArtifactMetadata, and more. beam_expansion_api.proto: ExpansionRequest/Response, DiscoverSchemaTransformRequest/Response, SchemaTransformConfig. beam_job_api.proto: JobService, JobInfo, JobStateEvent, JobMessage, GetJobMetricsRequest/Response, MetricResults, PipelineOptionType. beam_interactive_api.proto: TestStreamService, EventsRequest.
41b0d59 to
59b9ce1
Compare
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request focuses on enhancing the maintainability and usability of the Apache Beam model APIs by adding detailed documentation to the job management and interactive API protocol buffer definitions. By providing context for various services, messages, and fields, this change facilitates easier integration and understanding for developers working with cross-language pipeline construction and job monitoring. Highlights
New Features🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation comments to various Protobuf files to clarify the purpose of services, messages, fields, and enums. The feedback suggests specifying the expected string format (e.g., RFC 3339) for the time field in JobMessage to ensure consistent parsing, and correcting the description of attempted metrics in MetricResults to accurately reflect that they represent cumulative values across all execution attempts (including retries) rather than just "non-committed" computations.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| message JobMessage { | ||
| // (Required) A unique identifier for this message. | ||
| string message_id = 1; | ||
| // (Required) The time at which the message was emitted, as a string representation. |
There was a problem hiding this comment.
Since the time field is a string rather than a structured google.protobuf.Timestamp, it is highly recommended to specify the expected string format (e.g., RFC 3339 / ISO 8601). This ensures that different SDK and runner implementations serialize and parse the timestamp consistently.
| // (Required) The time at which the message was emitted, as a string representation. | |
| // (Required) The time at which the message was emitted, formatted as an RFC 3339 string. |
|
|
||
| // All metrics for a given job. Runners may support one or the other or both. | ||
| message MetricResults { | ||
| // Metrics reflecting the result of attempted (non-committed) computations. |
There was a problem hiding this comment.
The comment describes attempted metrics as representing 'non-committed' computations. In Apache Beam, attempted metrics actually represent the cumulative values across all execution attempts (including both successful/committed attempts and any failed or retried attempts). They are not exclusively 'non-committed' computations. Describing them as such is misleading.
| // Metrics reflecting the result of attempted (non-committed) computations. | |
| // Metrics reflecting the cumulative values across all execution attempts, including retries. |
|
Assigning reviewers: R: @Abacn added as fallback since no labels match configuration Note: If you would like to opt out of this review, comment Available commands:
The PR bot will only process comments in the main thread (not review comments). |
2 participants
Description
Add documentation comments to previously undocumented messages, fields, and enums in the Beam job management and interactive API protos.
Files Changed
beam_artifact_api.protobeam_expansion_api.protobeam_job_api.protobeam_interactive_api.protoNotes