CLI Unification: "Breaking Changes" section for release notes (#1024)

* cherry pick breaking changes pr to main branch

* create release notes dir

cmd/release-notes/prep/main.go

@@ -12,8 +12,8 @@ var (
 )
 
 func main() {
-	fileName := path.Join(".", "release-notes", "prep")
-	err := rn.WriteReleaseNotesPrep(fileName, releaseVersion, prevVersion)
+	filename := path.Join(".", "release-notes", "prep")
+	err := rn.WriteReleaseNotesPrep(filename, releaseVersion, prevVersion)
 	if err != nil {
 		panic(err)
 	}

internal/pkg/release-notes/docs_update_handler_test.go

@@ -14,6 +14,10 @@ func Test_Docs_Update_Handler(t *testing.T) {
 	newReleaseNotes := `|confluent-cli| v1.2.0 Release Notes
 ====================================
 
+Breaking Changes
+------------------------
+- 1.2 breaking change
+
 New Features
 ------------------------
 - v1.2.0 feature

internal/pkg/release-notes/prep-base

@@ -28,3 +28,7 @@ CONFLUENT
 %s
 - <PLACEHOLDER>
 
+
+%s
+- <PLACEHOLDER>
+

internal/pkg/release-notes/prep.go

@@ -7,31 +7,39 @@ import (
 	"os"
 	"os/exec"
 	"path"
+	"path/filepath"
 )
 
 const (
-	newFeaturesTitle = "New Features"
-	bugFixesTitle    = "Bug Fixes"
+	breakingChangesTitle = "Breaking Changes"
+	newFeaturesTitle     = "New Features"
+	bugFixesTitle        = "Bug Fixes"
 
 	prepFileName = "./release-notes/prep"
 	placeHolder  = "<PLACEHOLDER>"
 )
 
-func WriteReleaseNotesPrep(filename string, releaseVersion string, prevVersion string) error {
+func WriteReleaseNotesPrep(filename, releaseVersion, prevVersion string) error {
 	prepBaseFile := path.Join(".", "internal", "pkg", "release-notes", "prep-base")
 	prepBaseBytes, err := ioutil.ReadFile(prepBaseFile)
 	if err != nil {
 		return fmt.Errorf("unable to load release prep-base")
 	}
 	prepBaseString := string(prepBaseBytes)
-	f, err := os.Create(filename)
+
+	if err := os.MkdirAll(filepath.Dir(filename), os.ModePerm); err != nil {
+		return err
+	}
+
+	file, err := os.Create(filename)
 	if err != nil {
 		return err
 	}
-	defer f.Close()
+	defer file.Close()
+
 	mergedPRs := getMergedPRs(prevVersion)
-	prepFile := fmt.Sprintf(prepBaseString, releaseVersion, prevVersion, mergedPRs, newFeaturesTitle, bugFixesTitle)
-	_, err = io.WriteString(f, prepFile)
+	prepFile := fmt.Sprintf(prepBaseString, releaseVersion, prevVersion, mergedPRs, breakingChangesTitle, newFeaturesTitle, bugFixesTitle)
+	_, err = io.WriteString(file, prepFile)
 	return err
 }
 

internal/pkg/release-notes/prep_reader.go

@@ -11,14 +11,16 @@ import (
 type SectionType int
 
 const (
-	newFeaturesSection SectionType = iota
-	bugFixesSection
+	breakingChanges SectionType = iota
+	newFeatures
+	bugFixes
 )
 
 var (
 	sectionNameToSectionTypeMap = map[string]SectionType{
-		newFeaturesTitle: newFeaturesSection,
-		bugFixesTitle:    bugFixesSection,
+		breakingChangesTitle: breakingChanges,
+		newFeaturesTitle:     newFeatures,
+		bugFixesTitle:        bugFixes,
 	}
 	prepFileNotReadErrorMsg = "Prep file has not been read."
 )
@@ -34,8 +36,9 @@ type PrepFileReaderImpl struct {
 }
 
 type ReleaseNotesContent struct {
-	newFeatures []string
-	bugFixes    []string
+	breakingChanges []string
+	newFeatures     []string
+	bugFixes        []string
 }
 
 func NewPrepFileReader() PrepFileReader {
@@ -72,11 +75,7 @@ func (p *PrepFileReaderImpl) extractSections() error {
 			line = p.extractSectionContent(section)
 		}
 	}
-	err := p.scanner.Err()
-	if err != nil {
-		return err
-	}
-	return nil
+	return p.scanner.Err()
 }
 
 func (p *PrepFileReaderImpl) checkForSectionName(line string) (SectionType, bool) {
@@ -111,17 +110,17 @@ func (p *PrepFileReaderImpl) extractSectionContent(section SectionType) (lastLin
 }
 
 func (p *PrepFileReaderImpl) isPlaceHolder(element string) bool {
-	return element == placeHolder ||
-		(strings.HasPrefix(element, "<") && strings.HasSuffix(element, ">"))
+	return element == placeHolder || (strings.HasPrefix(element, "<") && strings.HasSuffix(element, ">"))
 }
 
 func (p *PrepFileReaderImpl) GetReleaseNotesContent() (*ReleaseNotesContent, error) {
 	if p.sections == nil {
 		return nil, errors.Errorf(prepFileNotReadErrorMsg)
 	}
 	content := &ReleaseNotesContent{
-		newFeatures: p.sections[newFeaturesSection],
-		bugFixes:    p.sections[bugFixesSection],
+		breakingChanges: p.sections[breakingChanges],
+		newFeatures:     p.sections[newFeatures],
+		bugFixes:        p.sections[bugFixes],
 	}
 	return content, nil
 }

internal/pkg/release-notes/prep_reader_test.go

@@ -8,59 +8,68 @@ import (
 
 func Test_Prep_Reader_Impl_Read_File(t *testing.T) {
 	tests := []struct {
-		name            string
-		prepFile        string
-		wantNewFeatures []string
-		wantBugFixes    []string
+		name                string
+		prepFile            string
+		wantBreakingChanges []string
+		wantNewFeatures     []string
+		wantBugFixes        []string
 	}{
 		{
-			name:            "test get sections with good formatting",
-			prepFile:        "test_files/prep1",
-			wantNewFeatures: []string{"feature1", "feature2"},
-			wantBugFixes:    []string{"bug1", "bug2"},
+			name:                "test get sections with good formatting",
+			prepFile:            "test_files/prep1",
+			wantBreakingChanges: []string{"breakingchange1", "breakingchange2"},
+			wantNewFeatures:     []string{"feature1", "feature2"},
+			wantBugFixes:        []string{"bug1", "bug2"},
 		},
 		{
-			name:            "test get sections with bad formatting",
-			prepFile:        "test_files/prep2",
-			wantNewFeatures: []string{"feature1", "feature2"},
-			wantBugFixes:    []string{"bug1", "bug2"},
+			name:                "test get sections with bad formatting",
+			prepFile:            "test_files/prep2",
+			wantBreakingChanges: []string{"breakingchange1", "breakingchange2"},
+			wantNewFeatures:     []string{"feature1", "feature2"},
+			wantBugFixes:        []string{"bug1", "bug2"},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			prepReader := PrepFileReaderImpl{}
 			err := prepReader.ReadPrepFile(tt.prepFile)
 			require.NoError(t, err)
-			require.Equal(t, prepReader.sections[newFeaturesSection], tt.wantNewFeatures)
-			require.Equal(t, prepReader.sections[bugFixesSection], tt.wantBugFixes)
+			require.Equal(t, prepReader.sections[newFeatures], tt.wantNewFeatures)
+			require.Equal(t, prepReader.sections[bugFixes], tt.wantBugFixes)
+			require.Equal(t, prepReader.sections[breakingChanges], tt.wantBreakingChanges)
 		})
 	}
 }
 
 func Test_Prep_Reader_Impl_Get_Content_Funcs(t *testing.T) {
 	tests := []struct {
-		name            string
-		sections        map[SectionType][]string
-		wantNewFeatures []string
-		wantBugFixes    []string
+		name                string
+		sections            map[SectionType][]string
+		wantBreakingChanges []string
+		wantNewFeatures     []string
+		wantBugFixes        []string
 	}{
 		{
 			name: "basic release notes",
 			sections: map[SectionType][]string{
-				newFeaturesSection: {"feature1", "feature2"},
-				bugFixesSection:    {"bug1", "bug2"},
+				breakingChanges: {"breakingchange1", "breakingchange2"},
+				newFeatures:     {"feature1", "feature2"},
+				bugFixes:        {"bug1", "bug2"},
 			},
-			wantNewFeatures: []string{"feature1", "feature2"},
-			wantBugFixes:    []string{"bug1", "bug2"},
+			wantBreakingChanges: []string{"breakingchange1", "breakingchange2"},
+			wantNewFeatures:     []string{"feature1", "feature2"},
+			wantBugFixes:        []string{"bug1", "bug2"},
 		},
 		{
 			name: "empty bug fixes",
 			sections: map[SectionType][]string{
-				newFeaturesSection: {"feature1", "feature2"},
-				bugFixesSection:    {},
+				breakingChanges: {"breakingchange1", "breakingchange2"},
+				newFeatures:     {"feature1", "feature2"},
+				bugFixes:        {},
 			},
-			wantNewFeatures: []string{"feature1", "feature2"},
-			wantBugFixes:    []string{},
+			wantBreakingChanges: []string{"breakingchange1", "breakingchange2"},
+			wantNewFeatures:     []string{"feature1", "feature2"},
+			wantBugFixes:        []string{},
 		},
 	}
 	for _, tt := range tests {

internal/pkg/release-notes/release-notes.go

@@ -71,11 +71,7 @@ func buildAndWriteReleaseNotes(version string, content *ReleaseNotesContent, doc
 	if err != nil {
 		return err
 	}
-	err = writeFile(updatedDocsFilePath, updatedDocsPage)
-	if err != nil {
-		return err
-	}
-	return nil
+	return writeFile(updatedDocsFilePath, updatedDocsPage)
 }
 
 func buildReleaseNotes(version string, releaseNotesBuildParams *ReleaseNotesBuilderParams, content *ReleaseNotesContent) string {

internal/pkg/release-notes/release_notes_builder.go

@@ -6,10 +6,11 @@ import (
 )
 
 const (
-	newFeaturesSectionTitle = "New Features"
-	bugFixesSectionTitle    = "Bug Fixes"
-	noChangeContentFormat   = "No changes relating to %s for this version."
-	bulletPointFormat       = "  - %s"
+	breakingChangesSectionTitle = "Breaking Changes"
+	newFeaturesSectionTitle     = "New Features"
+	bugFixesSectionTitle        = "Bug Fixes"
+	noChangeContentFormat       = "No changes relating to %s for this version."
+	bulletPointFormat           = "  - %s"
 )
 
 type ReleaseNotesBuilder interface {
@@ -35,10 +36,11 @@ func NewReleaseNotesBuilder(version string, params *ReleaseNotesBuilderParams) R
 }
 
 func (b *ReleaseNotesBuilderImpl) buildReleaseNotes(content *ReleaseNotesContent) string {
+	title := fmt.Sprintf(b.titleFormat, b.cliDisplayName, b.version)
+	breakingChangesSection := b.buildSection(breakingChangesSectionTitle, content.breakingChanges)
 	newFeaturesSection := b.buildSection(newFeaturesSectionTitle, content.newFeatures)
 	bugFixesSection := b.buildSection(bugFixesSectionTitle, content.bugFixes)
-	title := fmt.Sprintf(b.titleFormat, b.cliDisplayName, b.version)
-	return b.assembleReleaseNotes(title, newFeaturesSection, bugFixesSection)
+	return title + "\n" + b.getReleaseNotesContent(breakingChangesSection, newFeaturesSection, bugFixesSection)
 }
 
 func (b *ReleaseNotesBuilderImpl) buildSection(sectionTitle string, sectionElements []string) string {
@@ -58,20 +60,17 @@ func (b *ReleaseNotesBuilderImpl) buildBulletPoints(elements []string) string {
 	return strings.Join(bulletPointList, "\n")
 }
 
-func (b *ReleaseNotesBuilderImpl) assembleReleaseNotes(title string, newFeaturesSection string, bugFixesSection string) string {
-	content := b.getReleaseNotesContent(newFeaturesSection, bugFixesSection)
-	return title + "\n" + content
-}
+func (b *ReleaseNotesBuilderImpl) getReleaseNotesContent(sections ...string) string {
+	var fullSections []string
+	for _, section := range sections {
+		if section != "" {
+			fullSections = append(fullSections, section)
+		}
+	}
 
-func (b *ReleaseNotesBuilderImpl) getReleaseNotesContent(newFeaturesSection string, bugFixesSection string) string {
-	if newFeaturesSection == "" && bugFixesSection == "" {
+	if len(fullSections) == 0 {
 		return fmt.Sprintf(noChangeContentFormat, b.cliDisplayName)
 	}
-	if newFeaturesSection == "" {
-		return bugFixesSection
-	}
-	if bugFixesSection == "" {
-		return newFeaturesSection
-	}
-	return newFeaturesSection + "\n\n" + bugFixesSection
+
+	return strings.Join(fullSections, "\n\n")
 }

internal/pkg/release-notes/test_files/output/docs_update_handler_output

@@ -7,6 +7,10 @@
 |confluent-cli| v1.2.0 Release Notes
 ====================================
 
+Breaking Changes
+------------------------
+- 1.2 breaking change
+
 New Features
 ------------------------
 - v1.2.0 feature

internal/pkg/release-notes/test_files/prep1

@@ -21,6 +21,10 @@ NOTE: DO NOT EDIT THE SECTION TITLE
 CONFLUENT
 -------------
 
+Breaking Changes
+- breakingchange1
+- breakingchange2
+
 New Features
 - feature1
 - feature2

internal/pkg/release-notes/test_files/prep2

@@ -18,6 +18,9 @@ INSTRUCTIONS:
 NOTE: DO NOT EDIT THE SECTION TITLE
 
 
+Breaking Changes
+- breakingchange1
+- breakingchange2
 New Features
 -feature1
 -  feature2