Introduce a v2.x semver approval gate

Makefile

@@ -5,30 +5,22 @@
 # attention on files that are primarily Go.
 
 .PHONY: all
-all: generate lint tag-test test check-bin tag-check-bin gfmrun toc
+all: generate vet tag-test test check-binary-size tag-check-binary-size gfmrun toc v2diff
 
-.PHONY: generate
-generate:
-	go run internal/build/build.go generate
-
-.PHONY: lint
-lint:
-	go run internal/build/build.go vet
+# NOTE: this is a special catch-all rule to run any of the commands
+# defined in internal/build/build.go with optional arguments passed
+# via GFLAGS (global flags) and FLAGS (command-specific flags), e.g.:
+#
+#   $ make test GFLAGS='--packages cli'
+%:
+	go run internal/build/build.go $(GFLAGS) $* $(FLAGS)
 
 .PHONY: tag-test
 tag-test:
 	go run internal/build/build.go -tags urfave_cli_no_docs test
 
-.PHONY: test
-test:
-	go run internal/build/build.go test
-
-.PHONY: check-bin
-check-bin:
-	go run internal/build/build.go check-binary-size
-
-.PHONY: tag-check-bin
-tag-check-bin:
+.PHONY: tag-check-binary-size
+tag-check-binary-size:
 	go run internal/build/build.go -tags urfave_cli_no_docs check-binary-size
 
 .PHONY: gfmrun

docs/CONTRIBUTING.md

@@ -12,8 +12,9 @@ not get a response for many days.
 
 ### semantic versioning adherence
 
-The `urfave/cli` project strives to strictly adhere to semantic versioning. The active
-development branches and the milestones and import paths to which they correspond are:
+The `urfave/cli` project strives to strictly adhere to [semantic
+versioning](https://semver.org/spec/v2.0.0.html). The active development branches and the
+milestones and import paths to which they correspond are:
 
 #### `main` branch
 
@@ -25,6 +26,10 @@ which **MUST** *only* receive bug fixes and feature *additions*.
 - :arrow_right: [`v2.x`](https://github.com/urfave/cli/milestone/16)
 - :arrow_right: `github.com/urfave/cli/v2`
 
+The `main` branch in particular includes tooling to help with keeping the `v2.x` series
+backward compatible. More details on this process are in the development workflow section
+below.
+
 #### `v1` branch
 
 <https://github.com/urfave/cli/tree/v1>
@@ -63,6 +68,20 @@ verify one's changes are harmonious in nature. The same steps are also run durin
 [continuous integration
 phase](https://github.com/urfave/cli/blob/main/.github/workflows/cli.yml).
 
+In the event that the `v2diff` target exits non-zero, this is a signal that the public API
+surface area has changed. If the changes adhere to semantic versioning, meaning they are
+*additions* or *bug fixes*, then manually running the approval step will "promote" the
+current `go doc` output:
+
+```sh
+make v2approve
+```
+
+Because the `generate` step includes updating `godoc-current.txt` and
+`testdata/godoc-v2.x.txt`, these changes *MUST* be part of any proposed pull request so
+that reviewers have an opportunity to also make an informed decision about the "promotion"
+step.
+
 #### generated code
 
 A significant portion of the project's source code is generated, with the goal being to