feat: read release stage in auto generated docs from field in definit…

…ions (#68)

Because

- A `release_stage` field was
[introduced](instill-ai/connector#138) in
`definitions.json`

This commit

- Uses the field to render the release stage instead of extracting it
from `version` (which doesn't contain stages like GA, coming soon or
open for contributions).

tools/compogen/README.md

@@ -35,7 +35,9 @@ following fields must be present and comply with the following guidelines:
 - `description` - It should contain a single sentence describing the component.
   The template will use it next to the component title (`{{ .Title }}{{
   .Description }}.`) so it must be written in imperative tense.
-- `version` - Must be valid SemVer 2.0.0.
+- `release_stage` - Must be the string representation of one of the nonzero
+  values of `ComponentDefinition.ReleaseStage`,defined in
+  [protobufs](https://github.com/instill-ai/protobufs/blob/main/vdp/pipeline/v1beta/connector_definition.proto).
 - `type` - Connector definitions must contain this field and its value must
   match one of the (string) values defined in [protobufs](https://github.com/instill-ai/protobufs/blob/main/vdp/pipeline/v1beta/connector_definition.proto).
 - `available_tasks` - This array must have at least one value, which should be

tools/compogen/cmd/testdata/readme-connector.txt

@@ -46,7 +46,7 @@ cmp pkg/dummy/README.mdx want-readme.mdx
         "type": "object"
       }
     },
-    "version": "0.1.0-alpha",
+    "release_stage": "RELEASE_STAGE_COMING_SOON",
     "source_url": "https://github.com/instill-ai/connector/blob/main/pkg/dummy/v0"
   }
 ]
@@ -94,7 +94,7 @@ It can carry out the following tasks:
 
 ## Release Stage
 
-`Alpha`
+`Coming Soon`
 
 ## Configuration
 

tools/compogen/cmd/testdata/readme-operator.txt

@@ -34,7 +34,7 @@ cmp pkg/dummy/README.mdx want-readme.mdx
     "id": "dummy",
     "title": "Dummy",
     "description": "Perform an action",
-    "version": "0.1.0-alpha",
+    "release_stage": "RELEASE_STAGE_BETA",
     "source_url": "https://github.com/instill-ai/operator/blob/main/pkg/dummy/v0"
   }
 ]
@@ -167,7 +167,7 @@ It can carry out the following tasks:
 
 ## Release Stage
 
-`Alpha`
+`Beta`
 
 ## Configuration
 

tools/compogen/go.mod

@@ -5,9 +5,8 @@ go 1.21.5
 require (
 	github.com/frankban/quicktest v1.14.6
 	github.com/go-playground/validator/v10 v10.18.0
-	github.com/instill-ai/component v0.11.0-beta.0.20240222072616-52804d408e44
-	github.com/instill-ai/protogen-go v0.3.3-alpha.0.20240304063945-0080cc53de5e
-	github.com/launchdarkly/go-semver v1.0.2
+	github.com/instill-ai/component v0.13.0-beta
+	github.com/instill-ai/protogen-go v0.3.3-alpha.0.20240308151517-4b0523c184d1
 	github.com/rogpeppe/go-internal v1.12.0
 	github.com/russross/blackfriday/v2 v2.1.0
 	github.com/spf13/cobra v1.8.0

tools/compogen/go.sum

@@ -33,16 +33,14 @@ github.com/grpc-ecosystem/grpc-gateway/v2 v2.7.2 h1:I/pwhnUln5wbMnTyRbzswA0/JxpK
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.7.2/go.mod h1:lsuH8kb4GlMdSlI4alNIBBSAt5CHJtg3i+0WuN9J5YM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/instill-ai/component v0.11.0-beta.0.20240222072616-52804d408e44 h1:tcRZVBTROfWRH+E33KhoK8mn6pS5oHtXEQqpXzI5cnI=
-github.com/instill-ai/component v0.11.0-beta.0.20240222072616-52804d408e44/go.mod h1:THyROt2dqqge2lDc+PVzm/+LueG4dBtxpLzSjl+T83A=
-github.com/instill-ai/protogen-go v0.3.3-alpha.0.20240304063945-0080cc53de5e h1:fHbGDWVbaFFSrqRmy5cKDlBT/8nlsfS5m5LIo3P7Q70=
-github.com/instill-ai/protogen-go v0.3.3-alpha.0.20240304063945-0080cc53de5e/go.mod h1:jhEL0SauySMoPLVvx105DWyThju9sYTbsXIySVCArmM=
+github.com/instill-ai/component v0.13.0-beta h1:IY0Fky3WJCaHhiHwkwLU4G9KACUyar30OaOdeFvHq/Y=
+github.com/instill-ai/component v0.13.0-beta/go.mod h1:Zr3ej9EbkCe+lgSyzKhaqq8+mq84LGGP2F3OWOr/l3c=
+github.com/instill-ai/protogen-go v0.3.3-alpha.0.20240308151517-4b0523c184d1 h1:8bhIcJZcUMKvZas2L0uyaVt/V+Tzw0OSR8GtdcFflMo=
+github.com/instill-ai/protogen-go v0.3.3-alpha.0.20240308151517-4b0523c184d1/go.mod h1:jhEL0SauySMoPLVvx105DWyThju9sYTbsXIySVCArmM=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/launchdarkly/go-semver v1.0.2 h1:sYVRnuKyvxlmQCnCUyDkAhtmzSFRoX6rG2Xa21Mhg+w=
-github.com/launchdarkly/go-semver v1.0.2/go.mod h1:xFmMwXba5Mb+3h72Z+VeSs9ahCvKo2QFUTHRNHVqR28=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/lestrrat-go/jspointer v0.0.0-20181205001929-82fadba7561c h1:pGh5EFIfczeDHwgMHgfwjhZzL+8/E3uZF6T7vER/W8c=

tools/compogen/pkg/gen/definition.go

@@ -1,16 +1,47 @@
 package gen
 
+import (
+	"encoding/json"
+	"strings"
+
+	pb "github.com/instill-ai/protogen-go/vdp/pipeline/v1beta"
+	"golang.org/x/text/cases"
+	"golang.org/x/text/language"
+)
+
 type spec struct {
 	ResourceSpecification *objectSchema `json:"resource_specification" validate:"omitnil"`
 }
 
+type releaseStage pb.ComponentDefinition_ReleaseStage
+
+func (rs *releaseStage) UnmarshalJSON(b []byte) error {
+	var s string
+	if err := json.Unmarshal(b, &s); err != nil {
+		return err
+	}
+
+	*rs = releaseStage(pb.ComponentDefinition_ReleaseStage_value[s])
+	return nil
+}
+
+func (rs releaseStage) String() string {
+	pbRS := pb.ComponentDefinition_ReleaseStage(rs)
+	if pbRS == pb.ComponentDefinition_RELEASE_STAGE_GA {
+		return "GA"
+	}
+
+	upperSnake, _ := strings.CutPrefix(pbRS.String(), "RELEASE_STAGE_")
+	return cases.Title(language.English).String(strings.ReplaceAll(upperSnake, "_", " "))
+}
+
 type definition struct {
-	ID             string   `json:"id" validate:"required"`
-	Title          string   `json:"title" validate:"required"`
-	Description    string   `json:"description" validate:"required"`
-	Version        string   `json:"version" validate:"required,semver"`
-	AvailableTasks []string `json:"available_tasks" validate:"gt=0"`
-	SourceURL      string   `json:"source_url" validate:"url"`
+	ID             string       `json:"id" validate:"required"`
+	Title          string       `json:"title" validate:"required"`
+	Description    string       `json:"description" validate:"required"`
+	ReleaseStage   releaseStage `json:"release_stage" validate:"required"`
+	AvailableTasks []string     `json:"available_tasks" validate:"gt=0"`
+	SourceURL      string       `json:"source_url" validate:"url"`
 
 	Public        bool   `json:"public"`
 	Type          string `json:"type"`

tools/compogen/pkg/gen/definition_test.go

@@ -1,6 +1,7 @@
 package gen
 
 import (
+	"encoding/json"
 	"testing"
 
 	qt "github.com/frankban/quicktest"
@@ -19,7 +20,7 @@ func TestDefinition_Validate(t *testing.T) {
 			Title:          "Foo",
 			Description:    "Foo bar",
 			Public:         false,
-			Version:        "0.1.0-alpha",
+			ReleaseStage:   3,
 			AvailableTasks: []string{"TASK_1", "TASK_2"},
 			SourceURL:      "https://github.com/instill-ai",
 		}
@@ -57,18 +58,11 @@ func TestDefinition_Validate(t *testing.T) {
 			wantErr: "Description field is required",
 		},
 		{
-			name: "nok - no version",
+			name: "nok - no release stage",
 			modifier: func(d *definition) {
-				d.Version = ""
+				d.ReleaseStage = 0
 			},
-			wantErr: "Version field is required",
-		},
-		{
-			name: "nok - invalid version",
-			modifier: func(d *definition) {
-				d.Version = "v0.1.0-alpha"
-			},
-			wantErr: "Version field must be valid SemVer 2.0.0",
+			wantErr: "ReleaseStage field is required",
 		},
 		{
 			name: "nok - zero tasks",
@@ -117,3 +111,30 @@ func TestDefinition_Validate(t *testing.T) {
 		})
 	}
 }
+
+func TestReleaseStage_UnmarshalAndStringify(t *testing.T) {
+	c := qt.New(t)
+
+	testcases := []struct {
+		in   string
+		want string
+	}{
+		{in: "OTHER", want: "Unspecified"},
+		{in: "RELEASE_STAGE_OPEN_FOR_CONTRIBUTION", want: "Open For Contribution"},
+		{in: "RELEASE_STAGE_COMING_SOON", want: "Coming Soon"},
+		{in: "RELEASE_STAGE_ALPHA", want: "Alpha"},
+		{in: "RELEASE_STAGE_BETA", want: "Beta"},
+		{in: "RELEASE_STAGE_GA", want: "GA"},
+	}
+
+	for _, tc := range testcases {
+		c.Run(tc.in, func(c *qt.C) {
+			def := definition{}
+			j := json.RawMessage(`{"release_stage": "` + tc.in + `"}`)
+
+			err := json.Unmarshal(j, &def)
+			c.Check(err, qt.IsNil)
+			c.Check(def.ReleaseStage.String(), qt.Equals, tc.want)
+		})
+	}
+}

tools/compogen/pkg/gen/readme.go

@@ -6,16 +6,12 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"strings"
 	"text/template"
 	"unicode"
 	"unicode/utf8"
 
 	"github.com/go-playground/validator/v10"
-	"github.com/launchdarkly/go-semver"
 	"github.com/russross/blackfriday/v2"
-	"golang.org/x/text/cases"
-	"golang.org/x/text/language"
 
 	component "github.com/instill-ai/component/pkg/base"
 )
@@ -166,7 +162,7 @@ type readmeParams struct {
 	IsDraft          bool
 	ComponentType    ComponentType
 	ComponentSubtype ComponentSubtype
-	ReleaseStage     string
+	ReleaseStage     releaseStage
 	SourceURL        string
 	ResourceConfig   resourceConfig
 
@@ -183,11 +179,7 @@ func (p readmeParams) parseDefinition(d definition, tasks map[string]task) (read
 		return p, fmt.Errorf("invalid component type")
 	}
 
-	prerelease, err := versionToReleaseStage(d.Version)
-	if err != nil {
-		return p, err
-	}
-
+	var err error
 	if p.Tasks, err = parseREADMETasks(d.AvailableTasks, tasks); err != nil {
 		return p, err
 	}
@@ -196,7 +188,7 @@ func (p readmeParams) parseDefinition(d definition, tasks map[string]task) (read
 	p.Title = d.Title
 	p.Description = d.Description
 	p.IsDraft = !d.Public
-	p.ReleaseStage = prerelease
+	p.ReleaseStage = d.ReleaseStage
 	p.SourceURL = d.SourceURL
 
 	p.ResourceConfig = resourceConfig{Prerequisites: d.Prerequisites}
@@ -288,21 +280,3 @@ func firstToLower(s string) string {
 
 	return string(mod) + s[size:]
 }
-
-const generallyAvailable = "GA"
-
-func versionToReleaseStage(s string) (string, error) {
-	v, err := semver.Parse(s)
-	if err != nil {
-		return "", err
-	}
-
-	if prerelease := v.GetPrerelease(); prerelease != "" {
-		// If prerelease has several bits, use spaces. E.g.:
-		// "pre-release" -> "Pre Release"
-		rs := cases.Title(language.English).String(strings.ReplaceAll(prerelease, "-", " "))
-		return rs, nil
-	}
-
-	return generallyAvailable, nil
-}

tools/compogen/pkg/gen/readme_test.go

@@ -26,30 +26,6 @@ func TestFirstToLower(t *testing.T) {
 	}
 }
 
-func TestVersionToReleaseStage(t *testing.T) {
-	c := qt.New(t)
-
-	testcases := []struct {
-		in   string
-		want string
-	}{
-		{in: "0.1.0-alpha", want: "Alpha"},
-		{in: "1.0.0-alpha+001", want: "Alpha"},
-		{in: "0.1.0-beta", want: "Beta"},
-		{in: "1.0.0-beta+exp.sha", want: "Beta"},
-		{in: "0.1.0-pre-release", want: "Pre Release"},
-		{in: "0.1.0", want: "GA"},
-	}
-
-	for _, tc := range testcases {
-		c.Run(tc.in, func(c *qt.C) {
-			got, err := versionToReleaseStage(tc.in)
-			c.Check(err, qt.IsNil)
-			c.Check(got, qt.Equals, tc.want)
-		})
-	}
-}
-
 func TestComponentType_IndefiniteArticle(t *testing.T) {
 	c := qt.New(t)
 

tools/compogen/pkg/gen/resources/templates/readme.mdx.tmpl

@@ -12,7 +12,7 @@ It can carry out the following tasks:
 
 ## Release Stage
 
-`{{ .ReleaseStage }}`
+`{{ .ReleaseStage.String }}`
 
 ## Configuration