x
/
urfave-cli
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #1572 from urfave/explain-branches

Browse Source 
Update branch explanations and semver-ish automation
main
Dan Buch 2 years ago committed by GitHub
parent c296830b2b cbad251637
commit 766786fcc2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 41 additions and 47 deletions
Show Stats Download Patch File Download Diff File

9
.github/workflows/cli.yml vendored
Unescape View File

@ -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'
# }}

40
docs/CONTRIBUTING.md
Unescape View File

@ -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.

25
internal/build/build.go
Unescape View File

@ -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

14
testdata/godoc-v2.x.txt → testdata/godoc-v3.x.txt vendored
Unescape View File

@ -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
Write Preview
Loading…
Cancel
Save