From bcc2fceca880731327d03df06cf86b6a097f757f Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Thu, 2 May 2024 16:58:37 +0100 Subject: [PATCH] Add specification packages Add a go package that holds an unversioned alias of the API for creating events. This let user import the versioned package and have access to a simpler API which picks the right version of each event based on the spec version. There is still work to be done to support multiple versions, as the context may vary across versions, which is not yet handled. Signed-off-by: Andrea Frittoli --- README.md | 5 +- pkg/api/v0.3/docs.go | 260 +++++++++++++++++++++++++++++++++++ tools/generator.go | 29 +++- tools/templates/docs.go.tmpl | 33 +++++ 4 files changed, 320 insertions(+), 7 deletions(-) create mode 100644 pkg/api/v0.3/docs.go create mode 100644 tools/templates/docs.go.tmpl diff --git a/README.md b/README.md index d8867b3..b08eb2b 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,11 @@ Add the module as dependency using go mod: go get github.com/cdevents/sdk-go ``` -And import the module in your code +And import the module in your code corresponding to the desired version of the specification. +For CDEvents v0.3.x, use: ```golang -import cdevents "github.com/cdevents/sdk-go/pkg/api" +import cdevents "github.com/cdevents/sdk-go/pkg/api/v03" ``` ## Create your first CDEvent diff --git a/pkg/api/v0.3/docs.go b/pkg/api/v0.3/docs.go new file mode 100644 index 0000000..e91f0a1 --- /dev/null +++ b/pkg/api/v0.3/docs.go @@ -0,0 +1,260 @@ +// Code generated by tools/generator. DO NOT EDIT. + +/* +Copyright 2024 The CDEvents Authors + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +*/ + +// Package v03 contains method to create events that belong to the +// CDEvents specification v0.3.x + +package v03 + +import "github.com/cdevents/sdk-go/pkg/api" + +type ArtifactPackagedEvent = api.ArtifactPackagedEventV0_1_1 + +func NewArtifactPackagedEvent() (*ArtifactPackagedEvent, error) { + return api.NewArtifactPackagedEventV0_1_1() +} + +type ArtifactPublishedEvent = api.ArtifactPublishedEventV0_1_1 + +func NewArtifactPublishedEvent() (*ArtifactPublishedEvent, error) { + return api.NewArtifactPublishedEventV0_1_1() +} + +type ArtifactSignedEvent = api.ArtifactSignedEventV0_1_0 + +func NewArtifactSignedEvent() (*ArtifactSignedEvent, error) { + return api.NewArtifactSignedEventV0_1_0() +} + +type BranchCreatedEvent = api.BranchCreatedEventV0_1_2 + +func NewBranchCreatedEvent() (*BranchCreatedEvent, error) { + return api.NewBranchCreatedEventV0_1_2() +} + +type BranchDeletedEvent = api.BranchDeletedEventV0_1_2 + +func NewBranchDeletedEvent() (*BranchDeletedEvent, error) { + return api.NewBranchDeletedEventV0_1_2() +} + +type BuildFinishedEvent = api.BuildFinishedEventV0_1_1 + +func NewBuildFinishedEvent() (*BuildFinishedEvent, error) { + return api.NewBuildFinishedEventV0_1_1() +} + +type BuildQueuedEvent = api.BuildQueuedEventV0_1_1 + +func NewBuildQueuedEvent() (*BuildQueuedEvent, error) { + return api.NewBuildQueuedEventV0_1_1() +} + +type BuildStartedEvent = api.BuildStartedEventV0_1_1 + +func NewBuildStartedEvent() (*BuildStartedEvent, error) { + return api.NewBuildStartedEventV0_1_1() +} + +type ChangeAbandonedEvent = api.ChangeAbandonedEventV0_1_2 + +func NewChangeAbandonedEvent() (*ChangeAbandonedEvent, error) { + return api.NewChangeAbandonedEventV0_1_2() +} + +type ChangeCreatedEvent = api.ChangeCreatedEventV0_1_2 + +func NewChangeCreatedEvent() (*ChangeCreatedEvent, error) { + return api.NewChangeCreatedEventV0_1_2() +} + +type ChangeMergedEvent = api.ChangeMergedEventV0_1_2 + +func NewChangeMergedEvent() (*ChangeMergedEvent, error) { + return api.NewChangeMergedEventV0_1_2() +} + +type ChangeReviewedEvent = api.ChangeReviewedEventV0_1_2 + +func NewChangeReviewedEvent() (*ChangeReviewedEvent, error) { + return api.NewChangeReviewedEventV0_1_2() +} + +type ChangeUpdatedEvent = api.ChangeUpdatedEventV0_1_2 + +func NewChangeUpdatedEvent() (*ChangeUpdatedEvent, error) { + return api.NewChangeUpdatedEventV0_1_2() +} + +type EnvironmentCreatedEvent = api.EnvironmentCreatedEventV0_1_1 + +func NewEnvironmentCreatedEvent() (*EnvironmentCreatedEvent, error) { + return api.NewEnvironmentCreatedEventV0_1_1() +} + +type EnvironmentDeletedEvent = api.EnvironmentDeletedEventV0_1_1 + +func NewEnvironmentDeletedEvent() (*EnvironmentDeletedEvent, error) { + return api.NewEnvironmentDeletedEventV0_1_1() +} + +type EnvironmentModifiedEvent = api.EnvironmentModifiedEventV0_1_1 + +func NewEnvironmentModifiedEvent() (*EnvironmentModifiedEvent, error) { + return api.NewEnvironmentModifiedEventV0_1_1() +} + +type IncidentDetectedEvent = api.IncidentDetectedEventV0_1_0 + +func NewIncidentDetectedEvent() (*IncidentDetectedEvent, error) { + return api.NewIncidentDetectedEventV0_1_0() +} + +type IncidentReportedEvent = api.IncidentReportedEventV0_1_0 + +func NewIncidentReportedEvent() (*IncidentReportedEvent, error) { + return api.NewIncidentReportedEventV0_1_0() +} + +type IncidentResolvedEvent = api.IncidentResolvedEventV0_1_0 + +func NewIncidentResolvedEvent() (*IncidentResolvedEvent, error) { + return api.NewIncidentResolvedEventV0_1_0() +} + +type PipelineRunFinishedEvent = api.PipelineRunFinishedEventV0_1_1 + +func NewPipelineRunFinishedEvent() (*PipelineRunFinishedEvent, error) { + return api.NewPipelineRunFinishedEventV0_1_1() +} + +type PipelineRunQueuedEvent = api.PipelineRunQueuedEventV0_1_1 + +func NewPipelineRunQueuedEvent() (*PipelineRunQueuedEvent, error) { + return api.NewPipelineRunQueuedEventV0_1_1() +} + +type PipelineRunStartedEvent = api.PipelineRunStartedEventV0_1_1 + +func NewPipelineRunStartedEvent() (*PipelineRunStartedEvent, error) { + return api.NewPipelineRunStartedEventV0_1_1() +} + +type RepositoryCreatedEvent = api.RepositoryCreatedEventV0_1_1 + +func NewRepositoryCreatedEvent() (*RepositoryCreatedEvent, error) { + return api.NewRepositoryCreatedEventV0_1_1() +} + +type RepositoryDeletedEvent = api.RepositoryDeletedEventV0_1_1 + +func NewRepositoryDeletedEvent() (*RepositoryDeletedEvent, error) { + return api.NewRepositoryDeletedEventV0_1_1() +} + +type RepositoryModifiedEvent = api.RepositoryModifiedEventV0_1_1 + +func NewRepositoryModifiedEvent() (*RepositoryModifiedEvent, error) { + return api.NewRepositoryModifiedEventV0_1_1() +} + +type ServiceDeployedEvent = api.ServiceDeployedEventV0_1_1 + +func NewServiceDeployedEvent() (*ServiceDeployedEvent, error) { + return api.NewServiceDeployedEventV0_1_1() +} + +type ServicePublishedEvent = api.ServicePublishedEventV0_1_1 + +func NewServicePublishedEvent() (*ServicePublishedEvent, error) { + return api.NewServicePublishedEventV0_1_1() +} + +type ServiceRemovedEvent = api.ServiceRemovedEventV0_1_1 + +func NewServiceRemovedEvent() (*ServiceRemovedEvent, error) { + return api.NewServiceRemovedEventV0_1_1() +} + +type ServiceRolledbackEvent = api.ServiceRolledbackEventV0_1_1 + +func NewServiceRolledbackEvent() (*ServiceRolledbackEvent, error) { + return api.NewServiceRolledbackEventV0_1_1() +} + +type ServiceUpgradedEvent = api.ServiceUpgradedEventV0_1_1 + +func NewServiceUpgradedEvent() (*ServiceUpgradedEvent, error) { + return api.NewServiceUpgradedEventV0_1_1() +} + +type TaskRunFinishedEvent = api.TaskRunFinishedEventV0_1_1 + +func NewTaskRunFinishedEvent() (*TaskRunFinishedEvent, error) { + return api.NewTaskRunFinishedEventV0_1_1() +} + +type TaskRunStartedEvent = api.TaskRunStartedEventV0_1_1 + +func NewTaskRunStartedEvent() (*TaskRunStartedEvent, error) { + return api.NewTaskRunStartedEventV0_1_1() +} + +type TestCaseRunFinishedEvent = api.TestCaseRunFinishedEventV0_1_0 + +func NewTestCaseRunFinishedEvent() (*TestCaseRunFinishedEvent, error) { + return api.NewTestCaseRunFinishedEventV0_1_0() +} + +type TestCaseRunQueuedEvent = api.TestCaseRunQueuedEventV0_1_0 + +func NewTestCaseRunQueuedEvent() (*TestCaseRunQueuedEvent, error) { + return api.NewTestCaseRunQueuedEventV0_1_0() +} + +type TestCaseRunStartedEvent = api.TestCaseRunStartedEventV0_1_0 + +func NewTestCaseRunStartedEvent() (*TestCaseRunStartedEvent, error) { + return api.NewTestCaseRunStartedEventV0_1_0() +} + +type TestOutputPublishedEvent = api.TestOutputPublishedEventV0_1_0 + +func NewTestOutputPublishedEvent() (*TestOutputPublishedEvent, error) { + return api.NewTestOutputPublishedEventV0_1_0() +} + +type TestSuiteRunFinishedEvent = api.TestSuiteRunFinishedEventV0_1_0 + +func NewTestSuiteRunFinishedEvent() (*TestSuiteRunFinishedEvent, error) { + return api.NewTestSuiteRunFinishedEventV0_1_0() +} + +type TestSuiteRunQueuedEvent = api.TestSuiteRunQueuedEventV0_1_0 + +func NewTestSuiteRunQueuedEvent() (*TestSuiteRunQueuedEvent, error) { + return api.NewTestSuiteRunQueuedEventV0_1_0() +} + +type TestSuiteRunStartedEvent = api.TestSuiteRunStartedEventV0_1_0 + +func NewTestSuiteRunStartedEvent() (*TestSuiteRunStartedEvent, error) { + return api.NewTestSuiteRunStartedEventV0_1_0() +} diff --git a/tools/generator.go b/tools/generator.go index 131a9db..54891a6 100644 --- a/tools/generator.go +++ b/tools/generator.go @@ -69,6 +69,7 @@ var ( "examples_test.go.tmpl", "factory_test.go.tmpl", } + specTemplateFileName = "docs.go.tmpl" // Tool capitalizer cases.Caser @@ -106,7 +107,9 @@ type Data struct { } type AllData struct { - Slice []Data + Slice []Data + SpecVersion string + SpecVersionName string } func (d Data) OutputFile() string { @@ -141,7 +144,7 @@ func main() { for _, version := range SPEC_VERSIONS { versioned_schema_folder := filepath.Join(PROJECT_ROOT, SPEC_FOLDER_PREFIX+version, SCHEMA_FOLDER) log.Printf("Generating SDK files from templates: %s and schemas: %s into %s", TEMPLATES, versioned_schema_folder, GEN_CODE_FOLDER) - err = generate(TEMPLATES, versioned_schema_folder, GEN_CODE_FOLDER, "", GO_TYPES_NAMES) + err = generate(TEMPLATES, versioned_schema_folder, GEN_CODE_FOLDER, "", version, GO_TYPES_NAMES) if err != nil { log.Fatalf("%s", err.Error()) } @@ -150,17 +153,19 @@ func main() { // Generate SDK test files test_schema_folder := filepath.Join(PROJECT_ROOT, TEST_SCHEMA_FOLDER, SCHEMA_FOLDER) log.Printf("Generating SDK files from templates: %s and schemas: %s into %s", TEST_TEMPLATES, test_schema_folder, TEST_GEN_CODE_FOLDER) - err = generate(TEST_TEMPLATES, test_schema_folder, TEST_GEN_CODE_FOLDER, TEST_OUTPUT_PREFIX, GO_TYPES_TEST_NAMES) + err = generate(TEST_TEMPLATES, test_schema_folder, TEST_GEN_CODE_FOLDER, TEST_OUTPUT_PREFIX, "", GO_TYPES_TEST_NAMES) if err != nil { log.Fatalf("%s", err.Error()) } } -func generate(templatesFolder, schemaFolder, genFolder, prefix string, goTypes map[string]string) error { +func generate(templatesFolder, schemaFolder, genFolder, prefix, specVersion string, goTypes map[string]string) error { // allData is used to accumulate data from all jsonschemas // which is then used to run shared templates allData := AllData{ - Slice: make([]Data, 0), + Slice: make([]Data, 0), + SpecVersion: specVersion, + SpecVersionName: strings.Replace(specVersion, ".", "", -1), } allTemplates, err := template.ParseGlob(templatesFolder) @@ -182,6 +187,20 @@ func generate(templatesFolder, schemaFolder, genFolder, prefix string, goTypes m return err } + // Process the spec template. Create the target folder is it doesn't exist + if specVersion != "" { + specFileFolder := filepath.Join(genFolder, specVersion) + err = os.MkdirAll(specFileFolder, os.ModePerm) + if err != nil { + return err + } + specFileName := filepath.Join(genFolder, specVersion, strings.TrimSuffix(specTemplateFileName, filepath.Ext(specTemplateFileName))) + err = executeTemplate(allTemplates, specTemplateFileName, specFileName, allData) + if err != nil { + return err + } + } + // Process example test files - only for real data if prefix == "" { for _, examplesTestsTemplateFileName := range examplesTestsTemplateFileNames { diff --git a/tools/templates/docs.go.tmpl b/tools/templates/docs.go.tmpl new file mode 100644 index 0000000..3543d6b --- /dev/null +++ b/tools/templates/docs.go.tmpl @@ -0,0 +1,33 @@ +// Code generated by tools/generator. DO NOT EDIT. + +/* +Copyright 2024 The CDEvents Authors + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +*/ + +// Package v03 contains method to create events that belong to the +// CDEvents specification {{.SpecVersion}}.x + +package {{.SpecVersionName}} + +import "github.com/cdevents/sdk-go/pkg/api" + +{{- range $i, $data := .Slice }} +type {{.Subject}}{{.Predicate}}Event = api.{{.Subject}}{{.Predicate}}EventV{{.VersionName}} +func New{{.Subject}}{{.Predicate}}Event() (*{{.Subject}}{{.Predicate}}Event, error) { + return api.New{{.Subject}}{{.Predicate}}EventV{{.VersionName}}() +} +{{- end }}