Introduce a v2.x semver approval gate

internal/build/build.go

@@ -10,11 +10,29 @@ import (
 	"math"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 
 	"github.com/urfave/cli/v2"
 )
 
+const (
+	badNewsEmoji      = "🚨"
+	goodNewsEmoji     = "✨"
+	checksPassedEmoji = "✅"
+
+	v2diffWarning = `
+# The unified diff above indicates that the public API surface area
+# has changed. If you feel that the changes are acceptable and adhere
+# to the semantic versioning promise of the v2.x series described in
+# docs/CONTRIBUTING.md, please run the following command to promote
+# the current go docs:
+#
+#     make v2approve
+#
+`
+)
+
 func main() {
 	top, err := func() (string, error) {
 		if v, err := sh("git", "rev-parse", "--show-toplevel"); err == nil {
@@ -57,6 +75,17 @@ func main() {
 			Name:   "generate",
 			Action: GenerateActionFunc,
 		},
+		{
+			Name: "v2diff",
+			Flags: []cli.Flag{
+				&cli.BoolFlag{Name: "color", Value: false},
+			},
+			Action: V2Diff,
+		},
+		{
+			Name:   "v2approve",
+			Action: V2Approve,
+		},
 	}
 	app.Flags = []cli.Flag{
 		&cli.StringFlag{
@@ -206,9 +235,6 @@ func checkBinarySizeActionFunc(c *cli.Context) (err error) {
 		helloSourceFilePath  = "./internal/example-hello-world/example-hello-world.go"
 		helloBuiltFilePath   = "./internal/example-hello-world/built-example"
 		desiredMaxBinarySize = 2.2
-		badNewsEmoji         = "🚨"
-		goodNewsEmoji        = "✨"
-		checksPassedEmoji    = "✅"
 		mbStringFormatter    = "%.1fMB"
 	)
 
@@ -290,9 +316,68 @@ func checkBinarySizeActionFunc(c *cli.Context) (err error) {
 }
 
 func GenerateActionFunc(cCtx *cli.Context) error {
+	top := cCtx.Path("top")
+
+	cliDocs, err := sh("go", "doc", "-all", top)
+	if err != nil {
+		return err
+	}
+
+	altsrcDocs, err := sh("go", "doc", "-all", filepath.Join(top, "altsrc"))
+	if err != nil {
+		return err
+	}
+
+	if err := os.WriteFile(
+		filepath.Join(top, "godoc-current.txt"),
+		[]byte(cliDocs+altsrcDocs),
+		0644,
+	); err != nil {
+		return err
+	}
+
 	return runCmd("go", "generate", cCtx.Path("top")+"/...")
 }
 
+func V2Diff(cCtx *cli.Context) error {
+	os.Chdir(cCtx.Path("top"))
+
+	err := runCmd(
+		"diff",
+		"--ignore-all-space",
+		"--minimal",
+		"--color="+func() string {
+			if cCtx.Bool("color") {
+				return "always"
+			}
+			return "auto"
+		}(),
+		"--unified",
+		"--label=a/godoc",
+		filepath.Join("testdata", "godoc-v2.x.txt"),
+		"--label=b/godoc",
+		"godoc-current.txt",
+	)
+
+	if err != nil {
+		fmt.Printf("# %v ---> Hey! <---\n", badNewsEmoji)
+		fmt.Println(strings.TrimSpace(v2diffWarning))
+	}
+
+	return err
+}
+
+func V2Approve(cCtx *cli.Context) error {
+	top := cCtx.Path("top")
+
+	return runCmd(
+		"cp",
+		"-v",
+		filepath.Join(top, "godoc-current.txt"),
+		filepath.Join(top, "testdata", "godoc-v2.x.txt"),
+	)
+}
+
 func getSize(sourcePath string, builtPath string, tags string) (size int64, err error) {
 	// build example binary
 	err = runCmd("go", "build", "-tags", tags, "-o", builtPath, "-ldflags", "-s -w", sourcePath)