From cbad25163745719fbdececefa0fe79d92c38a4fe Mon Sep 17 00:00:00 2001 From: Dan Buch Date: Tue, 8 Nov 2022 13:13:58 -0500 Subject: [PATCH] Update branch explanations and semver-ish automation given move to main as v3 --- .github/workflows/cli.yml | 9 ++--- docs/CONTRIBUTING.md | 40 ++++++++++----------- internal/build/build.go | 25 +++++++------ testdata/{godoc-v2.x.txt => godoc-v3.x.txt} | 14 ++++---- 4 files changed, 41 insertions(+), 47 deletions(-) rename testdata/{godoc-v2.x.txt => godoc-v3.x.txt} (99%) diff --git a/.github/workflows/cli.yml b/.github/workflows/cli.yml index 5c8db7a..7df3e71 100644 --- a/.github/workflows/cli.yml +++ b/.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: 'false' - run: make v2diff - # }} + - if: matrix.go == '1.19.x' && matrix.os == 'ubuntu-latest' + run: make v3diff - 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' # }} diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d657477..c19e752 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -21,36 +21,33 @@ milestones and import paths to which they correspond are: 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: `github.com/urfave/cli/v2` +- :arrow_right: [`v3.x`](https://github.com/urfave/cli/milestone/5) +- :arrow_right: `github.com/urfave/cli/v3` -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. +The `main` branch includes tooling to help with keeping track of `v3.x` series backward +compatibility. More details on this process are in the development workflow section below. #### `v1` branch -The `v1` branch **MUST** only receive bug fixes in the `v1.22.x` series. There is no -strict rule regarding bug fixes to the `v2.x` series being backported to the `v1.22.x` -series. +The `v1` branch is no longer maintained. - :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 - + -The `v3-dev-branch` **MUST** receive all bug fixes and features added to the `main` branch -and **MAY** receive feature *removals* and other changes that are otherwise -*backward-incompatible* with the `v2.x` series. +The `v2-maint` branch **MUST** only receive bug fixes in the `v2.23.x` series. There is no +strict rule regarding bug fixes to the `v3.x` series being backported to the `v2.23.x` +series. -- :arrow_right: [`v3.x`](https://github.com/urfave/cli/milestone/5) -- unreleased / unsupported +- :arrow_right: [`v2.23.x`](https://github.com/urfave/cli/milestone/16) +- :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 -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: +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 are acceptable, then manually running the +approval step will "promote" the 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. diff --git a/internal/build/build.go b/internal/build/build.go index dcef50b..977a328 100644 --- a/internal/build/build.go +++ b/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 -# 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: +# has changed. If you feel that the changes are acceptable for the +# v3.x series, please run the following command to promote 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 diff --git a/testdata/godoc-v2.x.txt b/testdata/godoc-v3.x.txt similarity index 99% rename from testdata/godoc-v2.x.txt rename to testdata/godoc-v3.x.txt index ec5d863..9abda4b 100644 --- a/testdata/godoc-v2.x.txt +++ b/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