Move protos to their own directory for more consistency between different language bindings

Makefile

@@ -1,9 +1,10 @@
 go_setup:
 	go get google.golang.org/protobuf/cmd/[email protected]
 
-# Creates the go libs in the go/ directory.
-go_protos: go_setup
-	protoc --go_out=go --go_opt=paths=source_relative $(shell find ./spec -name "*.proto")
+protos: go_setup
+	make -C protos go
 
-run:
-	go run go/example/main.go
+go_run:
+	go run examples/go/main.go
+
+.PHONY: protos go_setup go_run

README.md

@@ -61,6 +61,6 @@ the framework. In the meantime, please visit any of the language-specific
 [in-toto implementations]: https://github.com/in-toto
 [issues]: https://github.com/in-toto/attestation/issues?q=is%3Aopen+is%3Aissue
 [overview]: spec/README.md#in-toto-attestation-framework-spec
-[protobuf definitions]: docs/protos.md
+[protobuf definitions]: protos/
 [pull requests]: https://github.com/in-toto/attestation/pulls?q=is%3Aopen+is%3Apr
 [specification]: spec/v1.0/

docs/protos.md

@@ -1,40 +1,76 @@
 # Spec protobuf definitions
 
 Protobuf definitions for the in-toto spec and some predicates are
-provided in the spec/ directory.  Pre-generated Go implementation of those
-protos are available in the go/ directory.
+provided in the [protos/] directory. We provide a list of
+[supported language bindings] for the spec and predicates.
+
+**DISCLAIMER**: The protobuf definitions and Golang bindings will not be
+considered stable until the v1.1 tagged release. Use at your own risk.
 
 ## Pre-requisites
 
 On an Ubuntu-based system, install the following dependencies.
 
 ```shell
-sudo apt install protobuf-compiler golang
+sudo apt install build-essential protobuf-compiler golang
 ```
 
+## Protobuf programming practices
+
+You should follow standard [protobuf programming practices] when developing
+a protobuf definition. In addition, we establish the following practices.
+
+### Package versioning
+
+To enable consumers to support multiple versions of the in-toto attestation
+spec or predicates[^1], 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 Go proto libraries
 
 [It's typical to keep generated Go code in the repository itself](https://go.dev/doc/articles/go_command#:~:text=and%20then%20check%20those%20generated%20source%20files%20into%20your%20repository)
 since it makes users' lives much easier.
 
-Proto libraries should be regenerated & commited after any change to the
-proto files:
+Proto libraries should be regenerated & committed after any change to the
+proto files. From the root directory, run:
 
 ```shell
-$ make go_protos
+$ make protos
 $ git commit -asm "update protos"
 ...
 ```
 
 ## Run the Go example
 
-go/example/main.go provides an example of how these protos can be used.
+examples/go/main.go provides an example of how these protos can be used.
 
 To try it:
 
 ```shell
-$ make run
+$ make go_run
 ...
 Read statement with predicateType https://example.com/unknownPred2
 Predicate fields:{key:"foo"  value:{struct_value:{fields:{key:"bar"  value:{string_value:"baz"}}}}}
 ```
+
+[^1]: This is especially helpful during transitions between major versions of the spec or predicate.
+
+[protobuf programming practices]: https://protobuf.dev/programming-guides/proto3
+[update guidelines]: https://protobuf.dev/programming-guides/proto3/#updating
+[protos/]: ../protos/
+[semver guidelines]: https://semver.org/#summary
+[supported language bindings]: ../protos/README.md#supported-language-bindings

go/example/main.go → examples/go/main.go

@@ -5,8 +5,8 @@ import (
 	"log"
 	"strings"
 
-	vpb "github.com/in-toto/attestation/go/spec/predicates/vsa"
-	spb "github.com/in-toto/attestation/go/spec/v1.0"
+	vpb "github.com/in-toto/attestation/go/predicates/vsa/v0"
+	spb "github.com/in-toto/attestation/go/v1"
 	"google.golang.org/protobuf/encoding/protojson"
 	"google.golang.org/protobuf/types/known/structpb"
 	"google.golang.org/protobuf/types/known/timestamppb"
@@ -16,8 +16,7 @@ func createStatementPbFromJson(subName string, subSha256 string, predicateType s
 	pred := &structpb.Struct{}
 	err := protojson.Unmarshal(predicateJson, pred)
 	if err != nil {
-		fmt.Errorf("failed to unmarshal predicate: %w", err)
-		return nil, err
+		return nil, fmt.Errorf("failed to unmarshal predicate: %w", err)
 	}
 	return createStatementPb(subName, subSha256, predicateType, pred), nil
 }
@@ -36,7 +35,7 @@ func createStatementPb(subName string, subSha256 string, predicateType string, p
 	return statement
 }
 
-func createVsa(subName string, subSha256 string, vsaBody *vpb.VerificationSummaryV02) (*spb.Statement, error) {
+func createVsa(subName string, subSha256 string, vsaBody *vpb.VerificationSummary) (*spb.Statement, error) {
 	vsaJson, err := protojson.Marshal(vsaBody)
 	if err != nil {
 		return nil, err
@@ -92,14 +91,14 @@ func main() {
 	fmt.Printf("Statement as json:\n%v\n", protojson.Format(s))
 
 	// Create a statement of a VSA
-	vsaPred := &vpb.VerificationSummaryV02{
-		Verifier: &vpb.VerificationSummaryV02_Verifier{
+	vsaPred := &vpb.VerificationSummary{
+		Verifier: &vpb.VerificationSummary_Verifier{
 			Id: "verifier-id"},
 		TimeVerified: timestamppb.Now(),
 		ResourceUri:  "http://example.com/the/protected/resource.tar",
-		Policy: &vpb.VerificationSummaryV02_Policy{
+		Policy: &vpb.VerificationSummary_Policy{
 			Uri: "http://example.com/policy/uri"},
-		InputAttestations: []*vpb.VerificationSummaryV02_InputAttestation{{
+		InputAttestations: []*vpb.VerificationSummary_InputAttestation{{
 			Uri:    "http://example.com/attestation/foo.intoto.jsonl",
 			Digest: map[string]string{"sha256": "def456"}},
 		},