standardize to always provide the description in the version

Signed-off-by: Jose I. Paris <jiparis@chainloop.dev>

Author: jiparis

app/cli/cmd/workflow_contract_describe.go

@@ -38,7 +38,7 @@ func newWorkflowContractDescribeCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "describe",
 		Short: "Describe the information of the contract",
-		RunE: func(cmd *cobra.Command, args []string) error {
+		RunE: func(_ *cobra.Command, _ []string) error {
 			res, err := action.NewWorkflowContractDescribe(ActionOpts).Run(name, revision)
 			if err != nil {
 				return err
@@ -83,19 +83,13 @@ func contractDescribeTableOutput(contractWithVersion *action.WorkflowContractWit
 	revision := contractWithVersion.Revision
 	c := contractWithVersion.Contract
 
-	// If available, show the description from the revision
-	description := c.Description
-	if revision.Description != "" {
-		description = revision.Description
-	}
-
 	t := output.NewTableWriter()
 	t.SetTitle("Contract")
 	t.AppendRow(table.Row{"Name", c.Name})
 	t.AppendSeparator()
 	t.AppendRow(table.Row{"Scope", c.ScopedEntity.String()})
 	t.AppendSeparator()
-	t.AppendRow(table.Row{"Description", description})
+	t.AppendRow(table.Row{"Description", revision.Description}) // description is always provided through
 	t.AppendSeparator()
 	t.AppendRow(table.Row{"Associated Workflows", stringifyAssociatedWorkflows(contractWithVersion)})
 	t.AppendSeparator()

app/controlplane/api/controlplane/v1/response_messages.pb.go

@@ -178,7 +178,8 @@ message PolicyReference {
 message WorkflowContractItem {
   string id = 1;
   string name = 2;
-  string description = 6;
+  // deprecated: description now belongs to the version, as it's versioned since the introduction of new contracts v2
+  string description = 6 [deprecated = true];
   google.protobuf.Timestamp created_at = 3;
   google.protobuf.Timestamp updated_at = 10;
   int32 latest_revision = 4;

app/controlplane/api/controlplane/v1/response_messages.proto

@@ -134,7 +134,7 @@ func (s *AttestationService) GetContract(ctx context.Context, req *cpAPI.Attesta
 
 	resp := &cpAPI.AttestationServiceGetContractResponse_Result{
 		Workflow: bizWorkflowToPb(wf),
-		Contract: bizWorkFlowContractVersionToPb(contractVersion.Version),
+		Contract: bizWorkFlowContractVersionToPb(contractVersion.Version, contractVersion.Contract),
 	}
 
 	return &cpAPI.AttestationServiceGetContractResponse{Result: resp}, nil

app/controlplane/api/gen/frontend/controlplane/v1/response_messages.ts

@@ -24,7 +24,7 @@ import (
 	"github.com/chainloop-dev/chainloop/app/controlplane/pkg/authz"
 	"github.com/chainloop-dev/chainloop/app/controlplane/pkg/biz"
 	"github.com/chainloop-dev/chainloop/app/controlplane/pkg/unmarshal"
-	errors "github.com/go-kratos/kratos/v2/errors"
+	"github.com/go-kratos/kratos/v2/errors"
 	"github.com/google/uuid"
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
@@ -91,7 +91,7 @@ func (s *WorkflowContractService) Describe(ctx context.Context, req *pb.Workflow
 
 	result := &pb.WorkflowContractServiceDescribeResponse_Result{
 		Contract: bizWorkFlowContractToPb(contractWithVersion.Contract),
-		Revision: bizWorkFlowContractVersionToPb(contractWithVersion.Version),
+		Revision: bizWorkFlowContractVersionToPb(contractWithVersion.Version, contractWithVersion.Contract),
 	}
 
 	return &pb.WorkflowContractServiceDescribeResponse{Result: result}, nil
@@ -199,7 +199,7 @@ func (s *WorkflowContractService) Update(ctx context.Context, req *pb.WorkflowCo
 
 	result := &pb.WorkflowContractServiceUpdateResponse_Result{
 		Contract: bizWorkFlowContractToPb(schemaWithVersion.Contract),
-		Revision: bizWorkFlowContractVersionToPb(schemaWithVersion.Version),
+		Revision: bizWorkFlowContractVersionToPb(schemaWithVersion.Version, schemaWithVersion.Contract),
 	}
 
 	return &pb.WorkflowContractServiceUpdateResponse{Result: result}, nil
@@ -261,7 +261,7 @@ func bizWorkFlowContractToPb(schema *biz.WorkflowContract) *pb.WorkflowContractI
 	return result
 }
 
-func bizWorkFlowContractVersionToPb(schema *biz.WorkflowContractVersion) *pb.WorkflowContractVersionItem {
+func bizWorkFlowContractVersionToPb(schema *biz.WorkflowContractVersion, contract *biz.WorkflowContract) *pb.WorkflowContractVersionItem {
 	formatTranslator := func(unmarshal.RawFormat) pb.WorkflowContractVersionItem_RawBody_Format {
 		switch schema.Schema.Format {
 		case unmarshal.RawFormatJSON:
@@ -288,8 +288,12 @@ func bizWorkFlowContractVersionToPb(schema *biz.WorkflowContractVersion) *pb.Wor
 		},
 	}
 
+	// Standardize the API to always provide description in the version.
+	// Add description from the proper source (new schemav2 or legacy top level contract)
 	if schema.Schema.Schemav2 != nil {
 		item.Description = schema.Schema.Schemav2.GetMetadata().GetDescription()
+	} else {
+		item.Description = contract.Description
 	}
 
 	return item

app/controlplane/api/gen/jsonschema/controlplane.v1.WorkflowContractItem.jsonschema.json

@@ -183,7 +183,7 @@ func (s *WorkflowRunService) View(ctx context.Context, req *pb.WorkflowRunServic
 
 	wr := bizWorkFlowRunToPb(run)
 	wr.Workflow = bizWorkflowToPb(run.Workflow)
-	wr.ContractVersion = bizWorkFlowContractVersionToPb(contractAndVersion.Version)
+	wr.ContractVersion = bizWorkFlowContractVersionToPb(contractAndVersion.Version, contractAndVersion.Contract)
 	wr.ContractVersion.ContractName = contractAndVersion.Contract.Name
 	res := &pb.WorkflowRunServiceViewResponse_Result{
 		WorkflowRun:  wr,

app/controlplane/api/gen/jsonschema/controlplane.v1.WorkflowContractItem.schema.json

@@ -34,8 +34,9 @@ import (
 )
 
 type WorkflowContract struct {
-	ID                      uuid.UUID
-	Name                    string
+	ID   uuid.UUID
+	Name string
+	// Deprecated: use description from the version instead
 	Description             string
 	LatestRevision          int
 	LatestRevisionCreatedAt *time.Time
@@ -71,6 +72,7 @@ type Contract struct {
 	// Detected format as provided by the user
 	Format unmarshal.RawFormat
 	// marshalled proto v1 contract
+	// Deprecated: use Schemav2 instead
 	Schema *schemav1.CraftingSchema
 	// marshalled proto v2 contract
 	Schemav2 *schemav1.CraftingSchemaV2