fix: reduce generator churn by removing goa version from file headers (#3902)

Remove the goa version string from per-file generated headers (Go and
proto) so that updating the goa dependency no longer causes every
generated file to change. The version is now recorded once in
gen/goa.json instead.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: disintegrator

codegen/generator/generate.go

@@ -156,13 +156,18 @@ func Generate(dir, cmd string, debug bool) (outputs []string, err1 error) {
 		}
 	}
 
-	// 8. Write the files (in parallel).
+	// 8. Emit goa.json version file (gen command only).
+	if cmd == "gen" {
+		genfiles = append(genfiles, codegen.VersionFile())
+	}
+
+	// 9. Write the files (in parallel).
 	written := make(map[string]struct{})
 	{
 		start := time.Now()
 		numWorkers := runtime.NumCPU()
 		if debug {
-			fmt.Fprintf(os.Stderr, "[TIMING]     [generate] Stage 8: Starting parallel file writing with %d workers\n", numWorkers)
+			fmt.Fprintf(os.Stderr, "[TIMING]     [generate] Stage 9: Starting parallel file writing with %d workers\n", numWorkers)
 		}
 
 		// Channel for work items
@@ -234,11 +239,11 @@ func Generate(dir, cmd string, debug bool) (outputs []string, err1 error) {
 		}
 
 		if debug {
-			fmt.Fprintf(os.Stderr, "[TIMING]     [generate] Stage 8: Write files took %v (%d files written, %d slow renders)\n", time.Since(start), len(written), slowRenders)
+			fmt.Fprintf(os.Stderr, "[TIMING]     [generate] Stage 9: Write files took %v (%d files written, %d slow renders)\n", time.Since(start), len(written), slowRenders)
 		}
 	}
 
-	// 9. Compute all output filenames.
+	// 10. Compute all output filenames.
 	{
 		start := time.Now()
 		outputs = make([]string, len(written))
@@ -256,7 +261,7 @@ func Generate(dir, cmd string, debug bool) (outputs []string, err1 error) {
 			i++
 		}
 		if debug {
-			fmt.Fprintf(os.Stderr, "[TIMING]     [generate] Stage 9: Compute output filenames took %v\n", time.Since(start))
+			fmt.Fprintf(os.Stderr, "[TIMING]     [generate] Stage 10: Compute output filenames took %v\n", time.Since(start))
 		}
 	}
 	sort.Strings(outputs)

codegen/generator/generate_merge_test.go

@@ -1,13 +1,15 @@
 package generator
 
 import (
+	"encoding/json"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 
 	"goa.design/goa/v3/codegen"
 	"goa.design/goa/v3/eval"
+	goa "goa.design/goa/v3/pkg"
 )
 
 // TestGenerateMergesSamePathFiles verifies that when two generators emit content
@@ -106,8 +108,9 @@ func TestGenerateParallelManyFiles(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Generate failed: %v", err)
 	}
+	outputs = assertVersionFile(t, dir, outputs)
 
-	// Verify all files were written
+	// Verify all generator files were written
 	if len(outputs) != numFiles {
 		t.Fatalf("expected %d output files, got %d", numFiles, len(outputs))
 	}
@@ -169,6 +172,7 @@ func TestGenerateParallelWithMerge(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Generate failed: %v", err)
 	}
+	outputs = assertVersionFile(t, dir, outputs)
 
 	if len(outputs) != 2 {
 		t.Fatalf("expected 2 output files, got %d", len(outputs))
@@ -268,6 +272,7 @@ func TestGenerateParallelSingleFile(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Generate failed: %v", err)
 	}
+	outputs = assertVersionFile(t, dir, outputs)
 
 	if len(outputs) != 1 {
 		t.Fatalf("expected 1 output file, got %d", len(outputs))
@@ -283,3 +288,33 @@ func TestGenerateParallelSingleFile(t *testing.T) {
 		t.Fatalf("file missing expected content:\n%s", content)
 	}
 }
+
+// assertVersionFile checks that goa.json was emitted with the correct version
+// and returns the remaining outputs (excluding goa.json) for further assertions.
+func assertVersionFile(t *testing.T, dir string, outputs []string) []string {
+	t.Helper()
+
+	versionPath := filepath.Join(codegen.Gendir, "goa.json")
+
+	// Read and validate goa.json content.
+	bs, err := os.ReadFile(filepath.Join(dir, versionPath))
+	if err != nil {
+		t.Fatalf("failed reading goa.json: %v", err)
+	}
+	var data map[string]string
+	if err := json.Unmarshal(bs, &data); err != nil {
+		t.Fatalf("goa.json is not valid JSON: %v", err)
+	}
+	if v := data["goa_version"]; v != goa.Version() {
+		t.Fatalf("goa.json version = %q, want %q", v, goa.Version())
+	}
+
+	// Filter goa.json out of outputs.
+	var rest []string
+	for _, o := range outputs {
+		if filepath.Base(o) != "goa.json" {
+			rest = append(rest, o)
+		}
+	}
+	return rest
+}

codegen/header.go

@@ -1,6 +1,9 @@
 package codegen
 
 import (
+	"encoding/json"
+	"path/filepath"
+
 	goa "goa.design/goa/v3/pkg"
 )
 
@@ -10,14 +13,27 @@ func Header(title, pack string, imports []*ImportSpec) *SectionTemplate {
 		Name:   "source-header",
 		Source: codegenTemplates.Read(headerT),
 		Data: map[string]any{
-			"Title":       title,
-			"ToolVersion": goa.Version(),
-			"Pkg":         pack,
-			"Imports":     imports,
+			"Title":   title,
+			"Pkg":     pack,
+			"Imports": imports,
 		},
 	}
 }
 
+// VersionFile returns a file that contains the goa version used to generate
+// the code. The file is written to gen/goa.json.
+func VersionFile() *File {
+	data := map[string]string{"goa_version": goa.Version()}
+	b, _ := json.MarshalIndent(data, "", "  ")
+	return &File{
+		Path: filepath.Join(Gendir, "goa.json"),
+		SectionTemplates: []*SectionTemplate{{
+			Name:   "goa-version",
+			Source: string(b),
+		}},
+	}
+}
+
 // AddImport adds imports to a section template that was generated with
 // Header.
 func AddImport(section *SectionTemplate, imprts ...*ImportSpec) {

codegen/sections_test.go

@@ -2,11 +2,8 @@ package codegen
 
 import (
 	"bytes"
-	"fmt"
 	"strings"
 	"testing"
-
-	goa "goa.design/goa/v3/pkg"
 )
 
 // normalizeLineEndings converts Windows line endings to Unix line endings
@@ -64,7 +61,7 @@ import (
 `
 	)
 	var (
-		titleHeader = fmt.Sprintf(`// Code generated by goa %s, DO NOT EDIT.
+		titleHeader = `// Code generated by goa, DO NOT EDIT.
 //
 // test title
 //
@@ -73,7 +70,7 @@ import (
 
 package testpackage
 
-`, goa.Version())
+`
 		imprt            = []*ImportSpec{{Path: "test"}}
 		imports          = append(imprt, &ImportSpec{Path: "other"})
 		pathImport       = []*ImportSpec{{Path: "import/with/slashes"}}

codegen/templates/header.go.tpl

@@ -1,4 +1,4 @@
-{{if .Title}}// Code generated by goa {{.ToolVersion}}, DO NOT EDIT.
+{{if .Title}}// Code generated by goa, DO NOT EDIT.
 //
 // {{.Title}}
 //

codegen/testutil/golden.go

@@ -40,19 +40,19 @@ type GoldenFile struct {
 }
 
 // goHeaderVersionRE matches the generated header line that contains the goa version (Go files).
-var goHeaderVersionRE = regexp.MustCompile(`(?m)^// Code generated by goa v[^,]+, DO NOT EDIT\.`)
+var goHeaderVersionRE = regexp.MustCompile(`(?m)^// Code generated by goa(?: v[^,]+)?, DO NOT EDIT\.`)
 
 // protoHeaderVersionRE matches the generated header line that contains the goa version (proto files).
-var protoHeaderVersionRE = regexp.MustCompile(`(?m)^// Code generated with goa v[^,]+, DO NOT EDIT\.`)
+var protoHeaderVersionRE = regexp.MustCompile(`(?m)^// Code generated with goa(?: v[^,]+)?, DO NOT EDIT\.`)
 
 // normalizeGoHeader replaces the versioned header with a version-agnostic placeholder.
 func normalizeGoHeader(b []byte) []byte {
-	return goHeaderVersionRE.ReplaceAll(b, []byte("// Code generated by goa vX, DO NOT EDIT."))
+	return goHeaderVersionRE.ReplaceAll(b, []byte("// Code generated by goa, DO NOT EDIT."))
 }
 
 // normalizeProtoHeader replaces the versioned header in .proto files with a version-agnostic placeholder.
 func normalizeProtoHeader(b []byte) []byte {
-	return protoHeaderVersionRE.ReplaceAll(b, []byte("// Code generated with goa vX, DO NOT EDIT."))
+	return protoHeaderVersionRE.ReplaceAll(b, []byte("// Code generated with goa, DO NOT EDIT."))
 }
 
 // NewGoldenFile creates a new GoldenFile instance with default options

grpc/codegen/proto.go

@@ -9,7 +9,6 @@ import (
 
 	"goa.design/goa/v3/codegen"
 	"goa.design/goa/v3/expr"
-	goa "goa.design/goa/v3/pkg"
 )
 
 const (
@@ -51,8 +50,7 @@ func protoFile(genpkg string, svc *expr.GRPCServiceExpr, services *ServicesData)
 			Name:   "proto-header",
 			Source: grpcTemplates.Read(grpcProtoHeaderT),
 			Data: map[string]any{
-				"Title":       fmt.Sprintf("%s protocol buffer definition", svc.Name()),
-				"ToolVersion": goa.Version(),
+				"Title": fmt.Sprintf("%s protocol buffer definition", svc.Name()),
 			},
 		},
 		// proto syntax and package

grpc/codegen/templates/proto_header.go.tpl

@@ -1,5 +1,5 @@
 {{ if .Title -}}
-// Code generated with goa {{ .ToolVersion }}, DO NOT EDIT.
+// Code generated with goa, DO NOT EDIT.
 //
 // {{ .Title }}
 //

grpc/codegen/testdata/golden/proto_array.proto.golden

@@ -1,4 +1,4 @@
-// Code generated with goa vX, DO NOT EDIT.
+// Code generated with goa, DO NOT EDIT.
 //
 // ServiceMessageArray protocol buffer definition
 //

grpc/codegen/testdata/golden/proto_map.proto.golden

@@ -1,4 +1,4 @@
-// Code generated with goa vX, DO NOT EDIT.
+// Code generated with goa, DO NOT EDIT.
 //
 // ServiceMessageMap protocol buffer definition
 //