Merge pull request #1572 from urfave/explain-branches
Update branch explanations and semver-ish automation
This commit is contained in:
GitHub
commit
766786fcc2
9
.github/workflows/cli.yml
vendored
9
.github/workflows/cli.yml
vendored
@ -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'
|
||||
# }}
|
||||
|
||||
@ -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: `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
|
||||
|
||||
<https://github.com/urfave/cli/tree/v1>
|
||||
|
||||
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
|
||||
|
||||
<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
|
||||
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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
Loading…
Reference in New Issue
Block a user