feat(vdp): add release stage to component definitions (#283)

Because - Component page and auto-generated docs require a release stage, and unimplemented stages (coming soon / open for contributions) shouldn't be extracted from the `version` field. - Reasons: they don't compare well (`0.1.0-alpha` < `0.1.0-alpha.coming-soon` < `0.1.0-coming-soon`), version isn't as good as an enum to filter out unimplemented versions (if in the future we use the component definition table for fetching the connectors / operators in the console). This commit - Adds and documents a `release_stage` enum and field to component definitions. ## ⏩ Next steps - Introduce property in existing `definitions.json` fields - Read this property when building the component definitions index in SQL. - Remove unimplemented components from [connector and operator lists](https://github.com/instill-ai/component/blob/main/pkg/base/connector.go#L177). Right now we don't have any component in this stage but as soon as we have one they will be load in the inmem list of definitions and they will appear in the console when building pipelines. - Update `compogen` to read release stages from this field instead of from `version` --------- Co-authored-by: droplet-bot <[email protected]>
instill-ai · Mar 8, 2024 · 8c20b4b · 8c20b4b
1 parent c4cdf98
commit 8c20b4b
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 0 deletions.
diff --git a/openapiv2/vdp/service.swagger.yaml b/openapiv2/vdp/service.swagger.yaml
@@ -3498,6 +3498,47 @@ definitions:
 
        - NAME_AVAILABLE: Available.
        - NAME_UNAVAILABLE: Unavailable.
+  ComponentDefinitionReleaseStage:
+    type: string
+    enum:
+      - RELEASE_STAGE_OPEN_FOR_CONTRIBUTION
+      - RELEASE_STAGE_COMING_SOON
+      - RELEASE_STAGE_ALPHA
+      - RELEASE_STAGE_BETA
+      - RELEASE_STAGE_GA
+    description: |-
+      - RELEASE_STAGE_OPEN_FOR_CONTRIBUTION: This component is unimplemented and community contributions are welcome
+      for this component.
+
+      It is recommended that the major and minor versions for definitions at
+      this release stage is kept at 0, e.g., `0.0.1`, `0.0.4`, etc.
+       - RELEASE_STAGE_COMING_SOON: The implementation of this component is planned and will be tackled by
+      the Instill AI team.
+
+      It is recommended that the major and minor versions for definitions at
+      this release stage is kept at 0, e.g., `0.0.1`, `0.0.4`, etc.
+       - RELEASE_STAGE_ALPHA: Initial implementation intended to gather feedback and issues from early
+      adopters. Alpha releases are discouraged for production use cases.
+
+      The `version` field in the definition must have `alpha` as its first
+      pre-release identifier, e.g., `0.1.0-alpha`, `0.1.3-alpha.1`.
+       - RELEASE_STAGE_BETA: The connector has reached stability and no backwards incompatible
+      changes are expected. Before reaching general availability, it should be
+      validated by a broader group of users. Some fixes might be added during
+      this process.
+
+      The `version` field in the definition must have `beta` as its first
+      pre-release identifier, e.g., `0.1.0-beta`, `0.1.3-beta.1`.
+       - RELEASE_STAGE_GA: Generally available - ready for use in production and fully supported by
+      Instill AI.
+    title: |-
+      ReleaseStage defines the release stage of a component. This is used to
+      group components with the same pre-relase groups (e.g. `0.1.0-beta`,
+      `0.1.0-beta.1` -> `RELEASE_STAGE_BETA`) and to include other "in progress"
+      (i.e. coming soon, open for contributions) stages that may not be relevant
+      within semantic versioning.
+      See the documentation of each value for potential constraints between
+      `version` and `release_stage` fields.`
   PipelinePublicServiceCloneOrganizationPipelineBody:
     type: object
     properties:
@@ -4396,6 +4437,10 @@ definitions:
         type: string
         description: Short description of the connector.
         readOnly: true
+      release_stage:
+        $ref: '#/definitions/ComponentDefinitionReleaseStage'
+        description: Release stage.
+        readOnly: true
     description: |-
       A Connector is a type of pipeline component that queries, processes or sends
       the ingested unstructured data to a service or app. Users need to configure
@@ -5118,6 +5163,10 @@ definitions:
         type: string
         description: Short description of the operator.
         readOnly: true
+      release_stage:
+        $ref: '#/definitions/ComponentDefinitionReleaseStage'
+        description: Release stage.
+        readOnly: true
     description: |-
       An Operator is a type of pipeline component that performs data injection and
       manipulation. OperatorDefinition describes a certain type of operator.

diff --git a/vdp/pipeline/v1beta/component_definition.proto b/vdp/pipeline/v1beta/component_definition.proto
@@ -28,6 +28,47 @@ message ComponentDefinition {
     VIEW_FULL = 2;
   }
 
+  // ReleaseStage defines the release stage of a component. This is used to
+  // group components with the same pre-relase groups (e.g. `0.1.0-beta`,
+  // `0.1.0-beta.1` -> `RELEASE_STAGE_BETA`) and to include other "in progress"
+  // (i.e. coming soon, open for contributions) stages that may not be relevant
+  // within semantic versioning.
+  // See the documentation of each value for potential constraints between
+  // `version` and `release_stage` fields.`
+  enum ReleaseStage {
+    // Unspecified.
+    RELEASE_STAGE_UNSPECIFIED = 0;
+    // This component is unimplemented and community contributions are welcome
+    // for this component.
+    //
+    // It is recommended that the major and minor versions for definitions at
+    // this release stage is kept at 0, e.g., `0.0.1`, `0.0.4`, etc.
+    RELEASE_STAGE_OPEN_FOR_CONTRIBUTION = 1;
+    // The implementation of this component is planned and will be tackled by
+    // the Instill AI team.
+    //
+    // It is recommended that the major and minor versions for definitions at
+    // this release stage is kept at 0, e.g., `0.0.1`, `0.0.4`, etc.
+    RELEASE_STAGE_COMING_SOON = 2;
+    // Initial implementation intended to gather feedback and issues from early
+    // adopters. Alpha releases are discouraged for production use cases.
+    //
+    // The `version` field in the definition must have `alpha` as its first
+    // pre-release identifier, e.g., `0.1.0-alpha`, `0.1.3-alpha.1`.
+    RELEASE_STAGE_ALPHA = 3;
+    // The connector has reached stability and no backwards incompatible
+    // changes are expected. Before reaching general availability, it should be
+    // validated by a broader group of users. Some fixes might be added during
+    // this process.
+    //
+    // The `version` field in the definition must have `beta` as its first
+    // pre-release identifier, e.g., `0.1.0-beta`, `0.1.3-beta.1`.
+    RELEASE_STAGE_BETA = 4;
+    // Generally available - ready for use in production and fully supported by
+    // Instill AI.
+    RELEASE_STAGE_GA = 5;
+  }
+
   // Defines the type of task the component will perform.
   ComponentType type = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
   // The component definition details.
@@ -143,6 +184,8 @@ message ConnectorDefinition {
   repeated ComponentTask tasks = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
   // Short description of the connector.
   string description = 18 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Release stage.
+  ComponentDefinition.ReleaseStage release_stage = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // OperatorSpec represents a specification data model.
@@ -209,6 +252,8 @@ message OperatorDefinition {
   repeated ComponentTask tasks = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
   // Short description of the operator.
   string description = 18 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Release stage.
+  ComponentDefinition.ReleaseStage release_stage = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 ///////////////////////////////////////////////////////////////////////