github.com/GoogleCloudPlatform/testgrid@v0.0.174/pb/README.md (about)

     1  # Protocol Buffers in TestGrid
     2  
     3  TestGrid stores its configuration, state, and other information in cloud storage
     4  encoded via these protocol buffers.
     5  
     6  ## Reading a Protocol Buffer
     7  
     8  Protocol buffers can be read using the proto compiler `protoc`. Be sure your
     9  working directory is this repository.
    10  
    11  This example uses gsutil to read a Configuration from Google Cloud Storage. Then,
    12  it uses protoc to decode it.
    13  ```bash
    14  gsutil cat gs://example-bucket/config | protoc --decode=Configuration pb/config/config.proto
    15  ```
    16  
    17  You need to pass protoc the proto name and file used to encode the file.
    18  
    19  These components generally generate these types of protos:
    20  
    21  | Component | Message | Source |
    22  |-----------|---------|--------|
    23  | Configurator or [Config Merger](/cmd/config_merger) | `Configuration` | [config.proto](./config/config.proto) |
    24  | [Summarizer](/cmd/summarizer) | `DashboardSummary` | [summary.proto](./summary/summary.proto) |
    25  | [Updater](/cmd/updater)  | `Grid` (see [Reading a Grid](#reading-a-grid))| [state.proto](./state/state.proto) |
    26  | [Tabulator](/cmd/tabulator) | `Grid` (see [Reading a Grid](#reading-a-grid)) | [state.proto](./state/state.proto) |
    27  
    28  ### Reading a Grid
    29  
    30  The Updater and Tabulator will compress its state as well as encoding it. To read it, you'll
    31  need to do one of the following:
    32  - In Go: Use [DownloadGrid()](/util/gcs/gcs.go) or `zlib.NewReader(reader)`
    33  - In shell: Use a script that will uncompress zlib, then pipe that result to `protoc`
    34  
    35  ### Reading an Unknown Protocol Buffer
    36  
    37  ```bash
    38  gsutil cat gs://example-bucket/config | protoc --decode_raw
    39  ```
    40  
    41  The result will use message numbers instead of message names. For example, `1`
    42  instead of `test_groups`
    43  
    44  ## Changing a Protocol Buffer Definition
    45  
    46  If you want to change one of the .proto files in this repository, you'll also
    47  need to regenerate the .pb.go files. Do so with this command:
    48  ```bash
    49  bazel run //hack:update-protos
    50  ```