Merge pull request #1572 from urfave/explain-branches

Update branch explanations and semver-ish automation

.github/workflows/cli.yml

@@ -46,11 +46,8 @@ jobs:
       - if: matrix.go == '1.19.x' && matrix.os == 'ubuntu-latest'
         run: make generate
       - run: make diffcheck
-      # TODO: switch once v3 is released {{
+      - if: matrix.go == '1.19.x' && matrix.os == 'ubuntu-latest'
-      # - if: matrix.go == '1.19.x' && matrix.os == 'ubuntu-latest'
+        run: make v3diff
-      - if: 'false'
-        run: make v2diff
-      # }}
       - if: success() && matrix.go == '1.19.x' && matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v3
         with:
@@ -78,7 +75,7 @@ jobs:
   publish:
     permissions:
       contents: write
-    # TODO: switch once v3 is released {{
+    # TODO: switch once v3 is out of alpha {{
     # if: startswith(github.ref, 'refs/tags/')
     if: 'false'
     # }}

docs/CONTRIBUTING.md

@@ -21,36 +21,33 @@ milestones and import paths to which they correspond are:
 <https://github.com/urfave/cli/tree/main>
 
 The majority of active development and issue management is targeting the `main` branch,
-which **MUST** *only* receive bug fixes and feature *additions*.
+which is currently in *alpha*.
 
-- :arrow_right: [`v2.x`](https://github.com/urfave/cli/milestone/16)
+- :arrow_right: [`v3.x`](https://github.com/urfave/cli/milestone/5)
-- :arrow_right: `github.com/urfave/cli/v2`
+- :arrow_right: `github.com/urfave/cli/v3`
 
-The `main` branch in particular includes tooling to help with keeping the `v2.x` series
+The `main` branch includes tooling to help with keeping track of `v3.x` series backward
-backward compatible. More details on this process are in the development workflow section
+compatibility. More details on this process are in the development workflow section below.
-below.
 
 #### `v1` branch
 
 <https://github.com/urfave/cli/tree/v1>
 
-The `v1` branch **MUST** only receive bug fixes in the `v1.22.x` series. There is no
+The `v1` branch is no longer maintained.
-strict rule regarding bug fixes to the `v2.x` series being backported to the `v1.22.x`
-series.
 
 - :arrow_right: [`v1.22.x`](https://github.com/urfave/cli/milestone/11)
 - :arrow_right: `github.com/urfave/cli`
 
-#### `v3-dev-main` branch
+#### `v2-maint` branch
 
-<https://github.com/urfave/cli/tree/v3-dev-main>
+<https://github.com/urfave/cli/tree/v2-maint>
 
-The `v3-dev-branch` **MUST** receive all bug fixes and features added to the `main` branch
+The `v2-maint` branch **MUST** only receive bug fixes in the `v2.23.x` series. There is no
-and **MAY** receive feature *removals* and other changes that are otherwise
+strict rule regarding bug fixes to the `v3.x` series being backported to the `v2.23.x`
-*backward-incompatible* with the `v2.x` series.
+series.
 
-- :arrow_right: [`v3.x`](https://github.com/urfave/cli/milestone/5)
+- :arrow_right: [`v2.23.x`](https://github.com/urfave/cli/milestone/16)
-- unreleased / unsupported
+- :arrow_right: `github.com/urfave/cli/v2`
 
 ### development workflow
 
@@ -68,17 +65,16 @@ 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
+In the event that the `v3diff` 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
+surface area has changed. If the changes are acceptable, then manually running the
-*additions* or *bug fixes*, then manually running the approval step will "promote" the
+approval step will "promote" the current `go doc` output:
-current `go doc` output:
 
 ```sh
-make v2approve
+make v3approve
 ```
 
 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
+`testdata/godoc-v3.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.
 

internal/build/build.go

@@ -28,14 +28,13 @@ const (
 
 	gfmrunVersion = "v1.3.0"
 
-	v2diffWarning = `
+	v3diffWarning = `
 # The unified diff above indicates that the public API surface area
-# has changed. If you feel that the changes are acceptable and adhere
+# has changed. If you feel that the changes are acceptable for the
-# to the semantic versioning promise of the v2.x series described in
+# v3.x series, please run the following command to promote the
-# docs/CONTRIBUTING.md, please run the following command to promote
+# current go docs:
-# the current go docs:
 #
-#     make v2approve
+#     make v3approve
 #
 `
 )
@@ -129,19 +128,19 @@ func main() {
 				Action: LintActionFunc,
 			},
 			{
-				Name: "v2diff",
+				Name: "v3diff",
 				Flags: []cli.Flag{
 					&cli.BoolFlag{Name: "color", Value: false},
 				},
-				Action: V2Diff,
+				Action: V3Diff,
 			},
 			{
-				Name: "v2approve",
+				Name: "v3approve",
 				Action: topRunAction(
 					"cp",
 					"-v",
 					"godoc-current.txt",
-					filepath.Join("testdata", "godoc-v2.x.txt"),
+					filepath.Join("testdata", "godoc-v3.x.txt"),
 				),
 			},
 		},
@@ -636,7 +635,7 @@ func LintActionFunc(cCtx *cli.Context) error {
 	return nil
 }
 
-func V2Diff(cCtx *cli.Context) error {
+func V3Diff(cCtx *cli.Context) error {
 	os.Chdir(cCtx.Path("top"))
 
 	err := runCmd(
@@ -651,14 +650,14 @@ func V2Diff(cCtx *cli.Context) error {
 		}(),
 		"--unified",
 		"--label=a/godoc",
-		filepath.Join("testdata", "godoc-v2.x.txt"),
+		filepath.Join("testdata", "godoc-v3.x.txt"),
 		"--label=b/godoc",
 		"godoc-current.txt",
 	)
 
 	if err != nil {
 		fmt.Printf("# %v ---> Hey! <---\n", badNewsEmoji)
-		fmt.Println(strings.TrimSpace(v2diffWarning))
+		fmt.Println(strings.TrimSpace(v3diffWarning))
 	}
 
 	return err

testdata/godoc-v3.x.txt

@@ -73,7 +73,8 @@ DESCRIPTION:
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
     CommandHelpTemplate is the text template for the command help topic. cli.go
     uses text/template to render templates. You can render custom help text by
     setting this variable.
@@ -144,7 +145,8 @@ COMMANDS:{{template "visibleCommandTemplate" .}}{{end}}{{if .VisibleFlagCategori
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
     SubcommandHelpTemplate is the text template for the subcommand help topic.
     cli.go uses text/template to render templates. You can render custom help
     text by setting this variable.
@@ -2092,7 +2094,7 @@ func (f *Uint64SliceFlag) Get(ctx *Context) []uint64
     Get returns the flag’s value in the given Context.
 
 func (f *Uint64SliceFlag) GetCategory() string
-    GetCategory returns the category for the flag
+    GetCategory returns the category of the flag
 
 func (f *Uint64SliceFlag) GetDefaultText() string
     GetDefaultText returns the default text for this flag
@@ -2129,7 +2131,7 @@ func (f *Uint64SliceFlag) String() string
     String returns a readable representation of this value (for usage defaults)
 
 func (f *Uint64SliceFlag) TakesValue() bool
-    TakesValue returns true of the flag takes a value, otherwise false
+    TakesValue returns true if the flag takes a value, otherwise false
 
 type UintFlag struct {
 	Name string
@@ -2256,7 +2258,7 @@ func (f *UintSliceFlag) Get(ctx *Context) []uint
     Get returns the flag’s value in the given Context.
 
 func (f *UintSliceFlag) GetCategory() string
-    GetCategory returns the category for the flag
+    GetCategory returns the category of the flag
 
 func (f *UintSliceFlag) GetDefaultText() string
     GetDefaultText returns the default text for this flag
@@ -2293,7 +2295,7 @@ func (f *UintSliceFlag) String() string
     String returns a readable representation of this value (for usage defaults)
 
 func (f *UintSliceFlag) TakesValue() bool
-    TakesValue returns true of the flag takes a value, otherwise false
+    TakesValue returns true if the flag takes a value, otherwise false
 
 type VisibleFlag interface {
 	Flag