refactor(changelog): sort entries, try to improve the naming

changelog/differ.go

@@ -4,26 +4,28 @@ import (
 	"encoding/json"
 	"fmt"
 	"slices"
+	"sort"
 	"strings"
 
+	"github.com/ettle/strcase"
 	"github.com/google/go-cmp/cmp"
 	"github.com/samber/lo"
 )
 
-func diffItems(resourceType ResourceType, was, have *Item) (*Diff, error) {
+func diffItems(resourceType RootType, was, have *Item) (*Diff, error) {
 	// Added or removed
 	if was == nil || have == nil {
-		action := ChangeTypeAdd
+		action := AddDiffAction
 		if have == nil {
-			action = ChangeTypeRemove
+			action = RemoveDiffAction
 			have = was
 		}
 
 		return &Diff{
-			Type:         action,
-			ResourceType: resourceType,
-			Description:  removeEnum(have.Description),
-			Item:         have,
+			Action:      action,
+			RootType:    resourceType,
+			Description: removeEnum(have.Description),
+			Item:        have,
 		}, nil
 	}
 
@@ -55,7 +57,7 @@ func diffItems(resourceType ResourceType, was, have *Item) (*Diff, error) {
 		case "deprecated":
 			entry = "remove deprecation"
 			if have.Deprecated != "" {
-				entry = fmt.Sprintf("deprecate: %s", have.Deprecated)
+				entry = fmt.Sprintf("deprecate: %s", strings.TrimRight(have.Deprecated, ". "))
 			}
 		case "beta":
 			entry = "marked as beta"
@@ -78,16 +80,16 @@ func diffItems(resourceType ResourceType, was, have *Item) (*Diff, error) {
 	}
 
 	return &Diff{
-		Type:         ChangeTypeChange,
-		ResourceType: resourceType,
-		Description:  strings.Join(entries, ", "),
-		Item:         have,
+		Action:      ChangeDiffAction,
+		RootType:    resourceType,
+		Description: strings.Join(entries, ", "),
+		Item:        have,
 	}, nil
 }
 
 func diffItemMaps(was, have ItemMap) ([]string, error) {
-	result := make([]string, 0)
-	kinds := []ResourceType{ResourceKind, DataSourceKind}
+	result := make([]*Diff, 0)
+	kinds := []RootType{ResourceRootType, DataSourceRootType}
 	for _, kind := range kinds {
 		wasItems := was[kind]
 		haveItems := have[kind]
@@ -105,6 +107,7 @@ func diffItemMaps(was, have ItemMap) ([]string, error) {
 			seen[k] = true
 
 			// When a resource added or removed, it skips all its fields until the next resource
+			// Otherwise, all its fields will appear as changes
 			if skipPrefix != "" && strings.HasPrefix(k, skipPrefix) {
 				continue
 			}
@@ -123,11 +126,32 @@ func diffItemMaps(was, have ItemMap) ([]string, error) {
 			}
 
 			if change != nil {
-				result = append(result, change.String())
+				result = append(result, change)
 			}
 		}
 	}
-	return result, nil
+
+	// Sorts changes by action, then by root type, then by root name
+	sort.Slice(result, func(i, j int) bool {
+		a, b := result[i], result[j]
+		if a.Action != b.Action {
+			return a.Action < b.Action
+		}
+
+		if a.Item.Path != b.Item.Path {
+			return a.Item.Path < b.Item.Path
+		}
+
+		// Resource comes first, then datasource
+		return a.RootType > b.RootType
+	})
+
+	strs := make([]string, len(result))
+	for i, r := range result {
+		strs[i] = r.String()
+	}
+
+	return strs, nil
 }
 
 func toMap(item *Item) (map[string]any, error) {
@@ -145,7 +169,15 @@ func toMap(item *Item) (map[string]any, error) {
 	m["enum"] = findEnums(item.Description)
 	m["beta"] = hasBeta(item.Description)
 	m["type"] = strValueType(item.Type)
-	m["elemType"] = strValueType(item.ElemType)
-	delete(m, "description") // Not needed to compare descriptions
+	m["elementType"] = strValueType(item.ElementType)
+
+	// Not needed to compare descriptions
+	delete(m, "description")
+
+	// Turns "maxItems" into "max items" for human readability
+	for k, v := range m {
+		delete(m, k)
+		m[strcase.ToCase(k, strcase.LowerCase, ' ')] = v
+	}
 	return m, err
 }

changelog/differ_test.go

@@ -11,13 +11,13 @@ func TestCompare(t *testing.T) {
 	tests := []struct {
 		name     string
 		expect   string
-		kind     ResourceType
+		kind     RootType
 		old, new *Item
 	}{
 		{
 			name:   "change enums",
-			expect: "Change resource `foo` field `bar`: enum ~~`bar`, `baz`~~ -> `foo`, `baz`",
-			kind:   ResourceKind,
+			expect: "Change `foo` resource field `bar`: enum ~~`bar`, `baz`~~ -> `foo`, `baz`",
+			kind:   ResourceRootType,
 			old: &Item{
 				Type:        schema.TypeString,
 				Path:        "foo.bar",
@@ -31,8 +31,8 @@ func TestCompare(t *testing.T) {
 		},
 		{
 			name:   "add resource field",
-			expect: "Add resource `foo` field `bar`: Foo",
-			kind:   ResourceKind,
+			expect: "Add `foo` resource field `bar`: Foo",
+			kind:   ResourceRootType,
 			new: &Item{
 				Type:        schema.TypeString,
 				Path:        "foo.bar",
@@ -41,8 +41,8 @@ func TestCompare(t *testing.T) {
 		},
 		{
 			name:   "remove resource field",
-			expect: "Remove resource `foo` field `bar`: Foo",
-			kind:   ResourceKind,
+			expect: "Remove `foo` resource field `bar`: Foo",
+			kind:   ResourceRootType,
 			old: &Item{
 				Type:        schema.TypeString,
 				Path:        "foo.bar",
@@ -51,8 +51,8 @@ func TestCompare(t *testing.T) {
 		},
 		{
 			name:   "remove beta from the field",
-			expect: "Change resource `foo` field `bar`: no longer beta",
-			kind:   ResourceKind,
+			expect: "Change `foo` resource field `bar`: no longer beta",
+			kind:   ResourceRootType,
 			old: &Item{
 				Type:        schema.TypeString,
 				Path:        "foo.bar",
@@ -66,8 +66,8 @@ func TestCompare(t *testing.T) {
 		},
 		{
 			name:   "add beta resource",
-			expect: "Add resource `foo` _(beta)_: does stuff, PROVIDER_AIVEN_ENABLE_BETA",
-			kind:   ResourceKind,
+			expect: "Add `foo` resource _(beta)_: does stuff, PROVIDER_AIVEN_ENABLE_BETA",
+			kind:   ResourceRootType,
 			new: &Item{
 				Type:        schema.TypeString,
 				Path:        "foo",
@@ -76,8 +76,8 @@ func TestCompare(t *testing.T) {
 		},
 		{
 			name:   "change type",
-			expect: "Change resource `foo` field `bar`: type ~~`list`~~ -> `set`",
-			kind:   ResourceKind,
+			expect: "Change `foo` resource field `bar`: type ~~`list`~~ -> `set`",
+			kind:   ResourceRootType,
 			old: &Item{
 				Type: schema.TypeList,
 				Path: "foo.bar",

changelog/main.go

@@ -155,9 +155,9 @@ func writeChangelog(_ string, entries []string) error {
 func fromProvider(p *schema.Provider) (ItemMap, error) {
 	// Item names might clash between resources and data sources
 	// Splits into separate maps
-	sourceMaps := map[ResourceType]map[string]*schema.Resource{
-		ResourceKind:   p.ResourcesMap,
-		DataSourceKind: p.DataSourcesMap,
+	sourceMaps := map[RootType]map[string]*schema.Resource{
+		ResourceRootType:   p.ResourcesMap,
+		DataSourceRootType: p.DataSourcesMap,
 	}
 
 	items := make(ItemMap)
@@ -200,7 +200,7 @@ func walkSchema(name string, this *schema.Schema, parent *Item) []*Item {
 	// Properties
 	switch elem := this.Elem.(type) {
 	case *schema.Schema:
-		item.ElemType = elem.Type
+		item.ElementType = elem.Type
 	case *schema.Resource:
 		for k, child := range elem.Schema {
 			items = append(items, walkSchema(k, child, item)...)

changelog/types.go

@@ -7,48 +7,51 @@ import (
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
 )
 
-type (
-	ResourceType string
-	DiffType     string
-)
+type RootType string
 
 const (
-	ResourceKind   ResourceType = "resource"
-	DataSourceKind ResourceType = "datasource"
+	ResourceRootType   RootType = "resource"
+	DataSourceRootType RootType = "datasource"
+)
+
+type DiffAction string
 
-	ChangeTypeAdd    DiffType = "Add"
-	ChangeTypeRemove DiffType = "Remove"
-	ChangeTypeChange DiffType = "Change"
+const (
+	AddDiffAction    DiffAction = "Add"
+	RemoveDiffAction DiffAction = "Remove"
+	ChangeDiffAction DiffAction = "Change"
 )
 
-type ItemMap map[ResourceType]map[string]*Item
+type ItemMap map[RootType]map[string]*Item
 
 type Item struct {
-	Name        string           `json:"name"`
-	Path        string           `json:"path"`
+	Path string `json:"path"` // e.g. aiven_project.project
+	Name string `json:"name"` // e.g. project
+
+	// Terraform schema fields
 	Description string           `json:"description"`
 	ForceNew    bool             `json:"forceNew"`
 	Optional    bool             `json:"optional"`
 	Sensitive   bool             `json:"sensitive"`
 	MaxItems    int              `json:"maxItems"`
 	Deprecated  string           `json:"deprecated"`
 	Type        schema.ValueType `json:"type"`
-	ElemType    schema.ValueType `json:"elemType"`
+	ElementType schema.ValueType `json:"elementType"`
 }
 
 type Diff struct {
-	Type         DiffType
-	ResourceType ResourceType
-	Description  string
-	Item         *Item
+	Action      DiffAction
+	RootType    RootType
+	Description string
+	Item        *Item
 }
 
 func (c *Diff) String() string {
 	// resource name + field name
 	path := strings.SplitN(c.Item.Path, ".", 2)
 
-	// e.g.: "Add resource `aiven_project`"
-	msg := fmt.Sprintf("%s %s `%s`", c.Type, c.ResourceType, path[0])
+	// e.g.: "Add `aiven_project` resource"
+	msg := fmt.Sprintf("%s `%s` %s", c.Action, path[0], c.RootType)
 
 	// e.g.: "field `project`"
 	if len(path) > 1 {

go.mod

@@ -8,6 +8,7 @@ require (
 	github.com/avast/retry-go v3.0.0+incompatible
 	github.com/dave/jennifer v1.7.1
 	github.com/docker/go-units v0.5.0
+	github.com/ettle/strcase v0.2.0
 	github.com/google/go-cmp v0.6.0
 	github.com/gruntwork-io/terratest v0.47.2
 	github.com/hamba/avro/v2 v2.27.0
@@ -17,6 +18,7 @@ require (
 	github.com/hashicorp/terraform-plugin-mux v0.17.0
 	github.com/hashicorp/terraform-plugin-sdk/v2 v2.34.0
 	github.com/kelseyhightower/envconfig v1.4.0
+	github.com/rs/zerolog v1.33.0
 	github.com/samber/lo v1.47.0
 	github.com/stoewer/go-strcase v1.3.0
 	github.com/stretchr/testify v1.9.0
@@ -41,7 +43,6 @@ require (
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/rs/zerolog v1.33.0 // indirect
 	github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.47.0 // indirect

go.sum

@@ -262,6 +262,8 @@ github.com/envoyproxy/go-control-plane v0.10.2-0.20220325020618-49ff273808a1/go.
 github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
 github.com/envoyproxy/protoc-gen-validate v1.1.0 h1:tntQDh69XqOCOZsDz0lVJQez/2L6Uu2PdjCQwWCJ3bM=
 github.com/envoyproxy/protoc-gen-validate v1.1.0/go.mod h1:sXRDRVmzEbkM7CVcM06s9shE/m23dg3wzjl0UWqJ2q4=
+github.com/ettle/strcase v0.2.0 h1:fGNiVF21fHXpX1niBgk0aROov1LagYsOwV/xqKDKR/Q=
+github.com/ettle/strcase v0.2.0/go.mod h1:DajmHElDSaX76ITe3/VHVyMin4LWSJN5Z909Wp+ED1A=
 github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=
 github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk=
 github.com/fatih/color v1.16.0 h1:zmkK9Ngbjj+K0yRhTVONQh1p/HknKYSlNT+vZCzyokM=