Skip to content

Latest commit

 

History

History
70 lines (49 loc) · 2.82 KB

protos.md

File metadata and controls

70 lines (49 loc) · 2.82 KB
Raw

Spec protobuf definitions

Protobuf definitions for the in-toto spec and some predicates are provided in the protos/ directory. We provide a list of supported language bindings for the spec and predicates.

DISCLAIMER: The protobuf definitions and language bindings will not be considered stable before the v1.1 tagged release. Use at your own risk.

Pre-requisites

On an Ubuntu-based system, install the following dependencies.

sudo apt install build-essential protobuf-compiler golang python3 python3-pip

Protobuf programming practices

You should follow standard protobuf programming practices when developing a protobuf definition.

NOTE: This means that while specification documents by convention use lowerCamelCase for field names, the protobuf definitions use lower_snake_case for field names per the standard protobuf convention.

We establish the following project specific practices, in addition to the standard protobuf programming practices:

Package versioning

To enable consumers to support multiple versions of the in-toto attestation spec or predicates1, we maintain versioned sub-packages for the protos.

This means, the protos for a new major version should be placed under new vMAJ sub-package under the respective protos package:

  • spec in protos/in\_toto\_attestation/
  • predicates in protos/in\_toto\_attestation/<predicate>/

Updates

Minor version updates to the protobufs are expected to be fully backwards compatible (per semver guidelines), and should be made directly to the proto defintions in the corresponding vMAJ sub-package.

To ensure backwards compatibility of the updated definition, please review the message type update guidelines.

Regenerating proto libraries

It's typical to keep code generated from protobuf definitions in the repository itself, since it makes users' lives much easier. However, do NOT manually regenerate and check in the libraries if your change modifies or adds protos.

To ensure libraries are generated using consistent tooling, we have automated their generation. Therefore, they will be regenerated automatically, after your change is merged.

Footnotes

  1. This is especially helpful during transitions between major versions of the spec or predicate. ↩