From 710df05119e25b836a2602efa439d22105a3d9d8 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sun, 29 Mar 2020 11:02:05 -0400 Subject: [PATCH 01/12] Add a v1 => v2 migration guide --- docs/v2/manual.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 71f5699917..2244f0cdbc 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -1424,6 +1424,166 @@ In this example the flag could be used like this : Side note: quotes may be necessary around the date depending on your layout (if you have spaces for instance) +### Converting from v1 to v2 + +v2 has a number of breaking changes but converting is straightforward: +make the changes documented below then resolve any compiler errors. +Typically this is sufficient. + +If you find any issues not covered by this document, please post a +comment on [Issue 921](https://github.com/urfave/cli/issues/921) or +consider sending a PR. + +#### Flags before args + +In v2 flags must come before args. This is more POSIX-compliant. You +may need to update scripts, user documentation, etc. + +This will work: + +``` +cli hello --shout rick +``` + +This will not: + +``` +cli hello rick --shout +``` + +#### Import string changed + +* OLD: `import "github.com/urfave/cli"` +* NEW: `import "github.com/urfave/cli/v2"` + +Check each file for this and make the change. + +Shell command to find them all: `fgrep -rl github.com/urfave/cli *` + +#### Flag aliases are done differently. + +Change `Name: "foo, f` to "Name: "foo", Aliases: []string{"f"}` + +OLD: + +``` +cli.StringFlag{ + Name: "config, cfg" +} +``` + +NEW: + +``` +cli.StringFlag{ + Name: "config", + Aliases: []string{"cfg"}, +} +``` + +Sadly v2 doesn't warn you if a comma is in the name. + +#### Commands are now lists of pointers + +Occurrences of `[]Command` have been changed to `[]*Command`. + +What this means to you: + +Look for `[]cli.Command{}` and change it to `[]*cli.Command{}` + +Example: + +* OLD: `var commands = []cli.Command{}` +* NEW: `var commands = []*cli.Command{}` + +Compiler messages you might see: + +` +commands/commands.go:56:30: cannot convert commands (type []cli.Command) to type cli.CommandsByName +commands/commands.go:57:15: cannot use commands (type []cli.Command) as type []*cli.Command in assignment +` + +#### Lists of commands should be pointers + +If you are building up a list of commands, the individual items should +now be pointers. + +* OLD: `cli.Command{` +* NEW: `&cli.Command{` + +Compiler messages you might see: + +` +./commands.go:32:34: cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to +` + +#### cli.Flag changed + +`cli.Flag` is now a list of pointers. + +What this means to you: + +If you make a list of flags, add a `&` in front of each +item. cli.BoolFlag, cli.StringFlag, etc. + +* OLD: +` + app.Flags = []cli.Flag{ + cli.BoolFlag{ +` + +* NEW: +``` + app.Flags = []cli.Flag{ + &cli.BoolFlag{ +``` + +Compiler messages you might see: + +``` + cli.StringFlag does not implement cli.Flag (Apply method has pointer receiver) +``` + +#### Appending Commands + +Appending to a list of commands needs to be changed since the list is +now pointers. + +* OLD: `commands = append(commands, *c)` +* NEW: `commands = append(commands, c)` + +Compiler messages you might see: + +` +commands/commands.go:28:19: cannot use c (type *cli.Command) as type cli.Command in append +` + +#### Actions returns errors + +A command's `Action:` now returns an `error`. + +* OLD: `Action: func(c *cli.Context) {` +* NEW: `Action: func(c *cli.Context) error {` + +Compiler messages you might see: + +``` +./commands.go:35:2: cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value +``` + +#### Everything else + +Compile the code and worth through any errors it finds. Most should +relate to issues listed above. + +Once it compiles, test the command. Make sure `-h` displays help +properly, then try various flags and subcommands. + +If you find anything not covered by this document please let us know +by submitting a comment on +[Issue 921](https://github.com/urfave/cli/issues/921) +so that others can benefit. + ### Full API Example **Notice**: This is a contrived (functioning) example meant strictly for API From 7a4368def7b62906b7f54ed9e30b4dbf800ada07 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sun, 29 Mar 2020 11:11:03 -0400 Subject: [PATCH 02/12] fixup! --- docs/v2/manual.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 2244f0cdbc..d62327786c 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -34,6 +34,7 @@ cli v2 manual * [Version Flag](#version-flag) + [Customization](#customization-2) * [Timestamp Flag](#timestamp-flag) + * [Migration Guide: v1 to v2](#migration-guide-v1-to-v2) * [Full API Example](#full-api-example) @@ -1424,15 +1425,16 @@ In this example the flag could be used like this : Side note: quotes may be necessary around the date depending on your layout (if you have spaces for instance) -### Converting from v1 to v2 +### Migration Guide: v1 to v2 -v2 has a number of breaking changes but converting is straightforward: -make the changes documented below then resolve any compiler errors. -Typically this is sufficient. +v2 has a number of breaking changes but converting is relatively +straightforward: make the changes documented below then resolve any +compiler errors. We hope this will be sufficient for most typical +users. If you find any issues not covered by this document, please post a comment on [Issue 921](https://github.com/urfave/cli/issues/921) or -consider sending a PR. +consider sending a PR to help improve this guide. #### Flags before args @@ -1498,10 +1500,10 @@ Example: Compiler messages you might see: -` +``` commands/commands.go:56:30: cannot convert commands (type []cli.Command) to type cli.CommandsByName commands/commands.go:57:15: cannot use commands (type []cli.Command) as type []*cli.Command in assignment -` +``` #### Lists of commands should be pointers @@ -1513,9 +1515,9 @@ now be pointers. Compiler messages you might see: -` +``` ./commands.go:32:34: cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to -` +``` #### cli.Flag changed @@ -1527,10 +1529,10 @@ If you make a list of flags, add a `&` in front of each item. cli.BoolFlag, cli.StringFlag, etc. * OLD: -` +``` app.Flags = []cli.Flag{ cli.BoolFlag{ -` +``` * NEW: ``` @@ -1554,9 +1556,9 @@ now pointers. Compiler messages you might see: -` +``` commands/commands.go:28:19: cannot use c (type *cli.Command) as type cli.Command in append -` +``` #### Actions returns errors From 228f1c9c58f2c615c81883cd5c98f683c04115b1 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sun, 29 Mar 2020 11:15:13 -0400 Subject: [PATCH 03/12] fixup! --- docs/v2/manual.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index d62327786c..8ad0e4e716 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -1575,13 +1575,14 @@ Compiler messages you might see: #### Everything else -Compile the code and worth through any errors it finds. Most should +Compile the code and work through any errors. Most should relate to issues listed above. -Once it compiles, test the command. Make sure `-h` displays help -properly, then try various flags and subcommands. +Once it compiles, test the command. Review the output of `-h` or any +help messages to verify they match the intended flags and subcommands. +Then test the program itself. -If you find anything not covered by this document please let us know +If you find any issues not covered by this document please let us know by submitting a comment on [Issue 921](https://github.com/urfave/cli/issues/921) so that others can benefit. From 6b3b21728cf96c7de5367fe254eb03d632f59f10 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sun, 29 Mar 2020 11:24:23 -0400 Subject: [PATCH 04/12] Fix TOC --- docs/v2/manual.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 8ad0e4e716..ea886d68a2 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -35,6 +35,15 @@ cli v2 manual + [Customization](#customization-2) * [Timestamp Flag](#timestamp-flag) * [Migration Guide: v1 to v2](#migration-guide-v1-to-v2) + [Flags before args](#flags-before-args) + [Import string changed](#import-string-changed) + [Flag aliases are done differently.](#flag-aliases-are-done-differently) + [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) + [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) + [cli.Flag changed](#cliflag-changed) + [Appending Commands](#appending-commands) + [Actions returns errors](#actions-returns-errors) + [Everything else](#everything-else) * [Full API Example](#full-api-example) From 9faa4e4097b194ba49bf3cd6f236ee96a34c867b Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sun, 29 Mar 2020 11:26:02 -0400 Subject: [PATCH 05/12] Fix TOC --- docs/v2/manual.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index ea886d68a2..099d950315 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -35,15 +35,15 @@ cli v2 manual + [Customization](#customization-2) * [Timestamp Flag](#timestamp-flag) * [Migration Guide: v1 to v2](#migration-guide-v1-to-v2) - [Flags before args](#flags-before-args) - [Import string changed](#import-string-changed) - [Flag aliases are done differently.](#flag-aliases-are-done-differently) - [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) - [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) - [cli.Flag changed](#cliflag-changed) - [Appending Commands](#appending-commands) - [Actions returns errors](#actions-returns-errors) - [Everything else](#everything-else) + + [Flags before args](#flags-before-args) + + [Import string changed](#import-string-changed) + + [Flag aliases are done differently.](#flag-aliases-are-done-differently) + + [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) + + [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) + + [cli.Flag changed](#cliflag-changed) + + [Appending Commands](#appending-commands) + + [Actions returns errors](#actions-returns-errors) + + [Everything else](#everything-else) * [Full API Example](#full-api-example) From caa97b585e0fa58bdbc15ef290527a99327f4ef7 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sun, 29 Mar 2020 11:29:34 -0400 Subject: [PATCH 06/12] Fix TOC --- docs/v2/manual.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 099d950315..cec89eba57 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -1475,16 +1475,14 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli *` Change `Name: "foo, f` to "Name: "foo", Aliases: []string{"f"}` -OLD: - +* OLD: ``` cli.StringFlag{ Name: "config, cfg" } ``` -NEW: - +* NEW: ``` cli.StringFlag{ Name: "config", From dc7ae10a155b9d9d52a9eea61edabe175bd31caa Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Mon, 30 Mar 2020 10:57:50 -0400 Subject: [PATCH 07/12] fixup! --- docs/v2/manual.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index cec89eba57..eab76d85e9 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -1438,7 +1438,7 @@ Side note: quotes may be necessary around the date depending on your layout (if v2 has a number of breaking changes but converting is relatively straightforward: make the changes documented below then resolve any -compiler errors. We hope this will be sufficient for most typical +compiler errors. We hope this will be sufficient for most typical users. If you find any issues not covered by this document, please post a @@ -1447,7 +1447,7 @@ consider sending a PR to help improve this guide. #### Flags before args -In v2 flags must come before args. This is more POSIX-compliant. You +In v2 flags must come before args. This is more POSIX-compliant. You may need to update scripts, user documentation, etc. This will work: @@ -1473,17 +1473,17 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli *` #### Flag aliases are done differently. -Change `Name: "foo, f` to "Name: "foo", Aliases: []string{"f"}` +Change `Name: "foo, f"` to `Name: "foo", Aliases: []string{"f"}` * OLD: -``` +```go cli.StringFlag{ Name: "config, cfg" } ``` * NEW: -``` +```go cli.StringFlag{ Name: "config", Aliases: []string{"cfg"}, @@ -1508,8 +1508,8 @@ Example: Compiler messages you might see: ``` -commands/commands.go:56:30: cannot convert commands (type []cli.Command) to type cli.CommandsByName -commands/commands.go:57:15: cannot use commands (type []cli.Command) as type []*cli.Command in assignment +cannot convert commands (type []cli.Command) to type cli.CommandsByName +cannot use commands (type []cli.Command) as type []*cli.Command in assignment ``` #### Lists of commands should be pointers @@ -1523,7 +1523,7 @@ now be pointers. Compiler messages you might see: ``` -./commands.go:32:34: cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to +cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to ``` #### cli.Flag changed @@ -1536,13 +1536,13 @@ If you make a list of flags, add a `&` in front of each item. cli.BoolFlag, cli.StringFlag, etc. * OLD: -``` +```go app.Flags = []cli.Flag{ cli.BoolFlag{ ``` * NEW: -``` +```go app.Flags = []cli.Flag{ &cli.BoolFlag{ ``` @@ -1564,7 +1564,7 @@ now pointers. Compiler messages you might see: ``` -commands/commands.go:28:19: cannot use c (type *cli.Command) as type cli.Command in append +cannot use c (type *cli.Command) as type cli.Command in append ``` #### Actions returns errors @@ -1577,7 +1577,7 @@ A command's `Action:` now returns an `error`. Compiler messages you might see: ``` -./commands.go:35:2: cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value +cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value ``` #### Everything else From 84c98fac3efcfcc289b9046400d470c602c22b56 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Tue, 31 Mar 2020 18:53:45 -0400 Subject: [PATCH 08/12] Move migration to a separate file.Move migration to a separate file --- docs/migrate-v1-to-v2.md | 175 +++++++++++++++++++++++++++++++++++++++ docs/v2/manual.md | 72 +++++++--------- 2 files changed, 206 insertions(+), 41 deletions(-) create mode 100644 docs/migrate-v1-to-v2.md diff --git a/docs/migrate-v1-to-v2.md b/docs/migrate-v1-to-v2.md new file mode 100644 index 0000000000..4bb676ceb9 --- /dev/null +++ b/docs/migrate-v1-to-v2.md @@ -0,0 +1,175 @@ +Migration Guide: v1 to v2 +=== + + + + * [Flags before args](#flags-before-args) + * [Import string changed](#import-string-changed) + * [Flag aliases are done differently.](#flag-aliases-are-done-differently) + * [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) + * [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) + * [cli.Flag changed](#cliflag-changed) + * [Appending Commands](#appending-commands) + * [Actions returns errors](#actions-returns-errors) + * [Everything else](#everything-else) + * [Full API Example](#full-api-example) + + + +v2 has a number of breaking changes but converting is relatively +straightforward: make the changes documented below then resolve any +compiler errors. We hope this will be sufficient for most typical +users. + +If you find any issues not covered by this document, please post a +comment on [Issue 921](https://github.com/urfave/cli/issues/921) or +consider sending a PR to help improve this guide. + +# Flags before args + +In v2 flags must come before args. This is more POSIX-compliant. You +may need to update scripts, user documentation, etc. + +This will work: + +``` +cli hello --shout rick +``` + +This will not: + +``` +cli hello rick --shout +``` + +# Import string changed + +* OLD: `import "github.com/urfave/cli"` +* NEW: `import "github.com/urfave/cli/v2"` + +Check each file for this and make the change. + +Shell command to find them all: `fgrep -rl github.com/urfave/cli *` + +# Flag aliases are done differently. + +Change `Name: "foo, f"` to `Name: "foo", Aliases: []string{"f"}` + +* OLD: +```go +cli.StringFlag{ + Name: "config, cfg" +} +``` + +* NEW: +```go +cli.StringFlag{ + Name: "config", + Aliases: []string{"cfg"}, +} +``` + +Sadly v2 doesn't warn you if a comma is in the name. + +# Commands are now lists of pointers + +Occurrences of `[]Command` have been changed to `[]*Command`. + +What this means to you: + +Look for `[]cli.Command{}` and change it to `[]*cli.Command{}` + +Example: + +* OLD: `var commands = []cli.Command{}` +* NEW: `var commands = []*cli.Command{}` + +Compiler messages you might see: + +``` +cannot convert commands (type []cli.Command) to type cli.CommandsByName +cannot use commands (type []cli.Command) as type []*cli.Command in assignment +``` + +# Lists of commands should be pointers + +If you are building up a list of commands, the individual items should +now be pointers. + +* OLD: `cli.Command{` +* NEW: `&cli.Command{` + +Compiler messages you might see: + +``` +cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to +``` + +# cli.Flag changed + +`cli.Flag` is now a list of pointers. + +What this means to you: + +If you make a list of flags, add a `&` in front of each +item. cli.BoolFlag, cli.StringFlag, etc. + +* OLD: +```go + app.Flags = []cli.Flag{ + cli.BoolFlag{ +``` + +* NEW: +```go + app.Flags = []cli.Flag{ + &cli.BoolFlag{ +``` + +Compiler messages you might see: + +``` + cli.StringFlag does not implement cli.Flag (Apply method has pointer receiver) +``` + +# Appending Commands + +Appending to a list of commands needs to be changed since the list is +now pointers. + +* OLD: `commands = append(commands, *c)` +* NEW: `commands = append(commands, c)` + +Compiler messages you might see: + +``` +cannot use c (type *cli.Command) as type cli.Command in append +``` + +# Actions returns errors + +A command's `Action:` now returns an `error`. + +* OLD: `Action: func(c *cli.Context) {` +* NEW: `Action: func(c *cli.Context) error {` + +Compiler messages you might see: + +``` +cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value +``` + +# Everything else + +Compile the code and work through any errors. Most should +relate to issues listed above. + +Once it compiles, test the command. Review the output of `-h` or any +help messages to verify they match the intended flags and subcommands. +Then test the program itself. + +If you find any issues not covered by this document please let us know +by submitting a comment on +[Issue 921](https://github.com/urfave/cli/issues/921) +so that others can benefit. diff --git a/docs/v2/manual.md b/docs/v2/manual.md index eab76d85e9..2244f0cdbc 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -34,16 +34,6 @@ cli v2 manual * [Version Flag](#version-flag) + [Customization](#customization-2) * [Timestamp Flag](#timestamp-flag) - * [Migration Guide: v1 to v2](#migration-guide-v1-to-v2) - + [Flags before args](#flags-before-args) - + [Import string changed](#import-string-changed) - + [Flag aliases are done differently.](#flag-aliases-are-done-differently) - + [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) - + [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) - + [cli.Flag changed](#cliflag-changed) - + [Appending Commands](#appending-commands) - + [Actions returns errors](#actions-returns-errors) - + [Everything else](#everything-else) * [Full API Example](#full-api-example) @@ -1434,20 +1424,19 @@ In this example the flag could be used like this : Side note: quotes may be necessary around the date depending on your layout (if you have spaces for instance) -### Migration Guide: v1 to v2 +### Converting from v1 to v2 -v2 has a number of breaking changes but converting is relatively -straightforward: make the changes documented below then resolve any -compiler errors. We hope this will be sufficient for most typical -users. +v2 has a number of breaking changes but converting is straightforward: +make the changes documented below then resolve any compiler errors. +Typically this is sufficient. If you find any issues not covered by this document, please post a comment on [Issue 921](https://github.com/urfave/cli/issues/921) or -consider sending a PR to help improve this guide. +consider sending a PR. #### Flags before args -In v2 flags must come before args. This is more POSIX-compliant. You +In v2 flags must come before args. This is more POSIX-compliant. You may need to update scripts, user documentation, etc. This will work: @@ -1473,17 +1462,19 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli *` #### Flag aliases are done differently. -Change `Name: "foo, f"` to `Name: "foo", Aliases: []string{"f"}` +Change `Name: "foo, f` to "Name: "foo", Aliases: []string{"f"}` -* OLD: -```go +OLD: + +``` cli.StringFlag{ Name: "config, cfg" } ``` -* NEW: -```go +NEW: + +``` cli.StringFlag{ Name: "config", Aliases: []string{"cfg"}, @@ -1507,10 +1498,10 @@ Example: Compiler messages you might see: -``` -cannot convert commands (type []cli.Command) to type cli.CommandsByName -cannot use commands (type []cli.Command) as type []*cli.Command in assignment -``` +` +commands/commands.go:56:30: cannot convert commands (type []cli.Command) to type cli.CommandsByName +commands/commands.go:57:15: cannot use commands (type []cli.Command) as type []*cli.Command in assignment +` #### Lists of commands should be pointers @@ -1522,9 +1513,9 @@ now be pointers. Compiler messages you might see: -``` -cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to -``` +` +./commands.go:32:34: cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to +` #### cli.Flag changed @@ -1536,13 +1527,13 @@ If you make a list of flags, add a `&` in front of each item. cli.BoolFlag, cli.StringFlag, etc. * OLD: -```go +` app.Flags = []cli.Flag{ cli.BoolFlag{ -``` +` * NEW: -```go +``` app.Flags = []cli.Flag{ &cli.BoolFlag{ ``` @@ -1563,9 +1554,9 @@ now pointers. Compiler messages you might see: -``` -cannot use c (type *cli.Command) as type cli.Command in append -``` +` +commands/commands.go:28:19: cannot use c (type *cli.Command) as type cli.Command in append +` #### Actions returns errors @@ -1577,19 +1568,18 @@ A command's `Action:` now returns an `error`. Compiler messages you might see: ``` -cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value +./commands.go:35:2: cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value ``` #### Everything else -Compile the code and work through any errors. Most should +Compile the code and worth through any errors it finds. Most should relate to issues listed above. -Once it compiles, test the command. Review the output of `-h` or any -help messages to verify they match the intended flags and subcommands. -Then test the program itself. +Once it compiles, test the command. Make sure `-h` displays help +properly, then try various flags and subcommands. -If you find any issues not covered by this document please let us know +If you find anything not covered by this document please let us know by submitting a comment on [Issue 921](https://github.com/urfave/cli/issues/921) so that others can benefit. From be370eb48562419efe420919b7ac1ac3f918d338 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Tue, 31 Mar 2020 18:58:39 -0400 Subject: [PATCH 09/12] Re-order items to be more logical. --- docs/migrate-v1-to-v2.md | 93 ++++++++++++++++++++-------------------- 1 file changed, 47 insertions(+), 46 deletions(-) diff --git a/docs/migrate-v1-to-v2.md b/docs/migrate-v1-to-v2.md index 4bb676ceb9..8d56a39935 100644 --- a/docs/migrate-v1-to-v2.md +++ b/docs/migrate-v1-to-v2.md @@ -1,6 +1,16 @@ Migration Guide: v1 to v2 === + +v2 has a number of breaking changes but converting is relatively +straightforward: make the changes documented below then resolve any +compiler errors. We hope this will be sufficient for most typical +users. + +If you find any issues not covered by this document, please post a +comment on [Issue 921](https://github.com/urfave/cli/issues/921) or +consider sending a PR to help improve this guide. + * [Flags before args](#flags-before-args) @@ -16,15 +26,6 @@ Migration Guide: v1 to v2 -v2 has a number of breaking changes but converting is relatively -straightforward: make the changes documented below then resolve any -compiler errors. We hope this will be sufficient for most typical -users. - -If you find any issues not covered by this document, please post a -comment on [Issue 921](https://github.com/urfave/cli/issues/921) or -consider sending a PR to help improve this guide. - # Flags before args In v2 flags must come before args. This is more POSIX-compliant. You @@ -72,38 +73,17 @@ cli.StringFlag{ Sadly v2 doesn't warn you if a comma is in the name. -# Commands are now lists of pointers - -Occurrences of `[]Command` have been changed to `[]*Command`. - -What this means to you: - -Look for `[]cli.Command{}` and change it to `[]*cli.Command{}` - -Example: - -* OLD: `var commands = []cli.Command{}` -* NEW: `var commands = []*cli.Command{}` - -Compiler messages you might see: - -``` -cannot convert commands (type []cli.Command) to type cli.CommandsByName -cannot use commands (type []cli.Command) as type []*cli.Command in assignment -``` - -# Lists of commands should be pointers +# Actions returns errors -If you are building up a list of commands, the individual items should -now be pointers. +A command's `Action:` now returns an `error`. -* OLD: `cli.Command{` -* NEW: `&cli.Command{` +* OLD: `Action: func(c *cli.Context) {` +* NEW: `Action: func(c *cli.Context) error {` Compiler messages you might see: ``` -cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to +cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value ``` # cli.Flag changed @@ -133,31 +113,52 @@ Compiler messages you might see: cli.StringFlag does not implement cli.Flag (Apply method has pointer receiver) ``` -# Appending Commands +# Commands are now lists of pointers -Appending to a list of commands needs to be changed since the list is -now pointers. +Occurrences of `[]Command` have been changed to `[]*Command`. -* OLD: `commands = append(commands, *c)` -* NEW: `commands = append(commands, c)` +What this means to you: + +Look for `[]cli.Command{}` and change it to `[]*cli.Command{}` + +Example: + +* OLD: `var commands = []cli.Command{}` +* NEW: `var commands = []*cli.Command{}` Compiler messages you might see: ``` -cannot use c (type *cli.Command) as type cli.Command in append +cannot convert commands (type []cli.Command) to type cli.CommandsByName +cannot use commands (type []cli.Command) as type []*cli.Command in assignment ``` -# Actions returns errors +# Lists of commands should be pointers -A command's `Action:` now returns an `error`. +If you are building up a list of commands, the individual items should +now be pointers. -* OLD: `Action: func(c *cli.Context) {` -* NEW: `Action: func(c *cli.Context) error {` +* OLD: `cli.Command{` +* NEW: `&cli.Command{` Compiler messages you might see: ``` -cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value +cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to +``` + +# Appending Commands + +Appending to a list of commands needs to be changed since the list is +now pointers. + +* OLD: `commands = append(commands, *c)` +* NEW: `commands = append(commands, c)` + +Compiler messages you might see: + +``` +cannot use c (type *cli.Command) as type cli.Command in append ``` # Everything else From 200fa41ab392d869f062fa05c36c0fb952fc6fee Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Tue, 31 Mar 2020 18:59:44 -0400 Subject: [PATCH 10/12] Revert v2/manual.md --- docs/v2/manual.md | 160 ---------------------------------------------- 1 file changed, 160 deletions(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 2244f0cdbc..71f5699917 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -1424,166 +1424,6 @@ In this example the flag could be used like this : Side note: quotes may be necessary around the date depending on your layout (if you have spaces for instance) -### Converting from v1 to v2 - -v2 has a number of breaking changes but converting is straightforward: -make the changes documented below then resolve any compiler errors. -Typically this is sufficient. - -If you find any issues not covered by this document, please post a -comment on [Issue 921](https://github.com/urfave/cli/issues/921) or -consider sending a PR. - -#### Flags before args - -In v2 flags must come before args. This is more POSIX-compliant. You -may need to update scripts, user documentation, etc. - -This will work: - -``` -cli hello --shout rick -``` - -This will not: - -``` -cli hello rick --shout -``` - -#### Import string changed - -* OLD: `import "github.com/urfave/cli"` -* NEW: `import "github.com/urfave/cli/v2"` - -Check each file for this and make the change. - -Shell command to find them all: `fgrep -rl github.com/urfave/cli *` - -#### Flag aliases are done differently. - -Change `Name: "foo, f` to "Name: "foo", Aliases: []string{"f"}` - -OLD: - -``` -cli.StringFlag{ - Name: "config, cfg" -} -``` - -NEW: - -``` -cli.StringFlag{ - Name: "config", - Aliases: []string{"cfg"}, -} -``` - -Sadly v2 doesn't warn you if a comma is in the name. - -#### Commands are now lists of pointers - -Occurrences of `[]Command` have been changed to `[]*Command`. - -What this means to you: - -Look for `[]cli.Command{}` and change it to `[]*cli.Command{}` - -Example: - -* OLD: `var commands = []cli.Command{}` -* NEW: `var commands = []*cli.Command{}` - -Compiler messages you might see: - -` -commands/commands.go:56:30: cannot convert commands (type []cli.Command) to type cli.CommandsByName -commands/commands.go:57:15: cannot use commands (type []cli.Command) as type []*cli.Command in assignment -` - -#### Lists of commands should be pointers - -If you are building up a list of commands, the individual items should -now be pointers. - -* OLD: `cli.Command{` -* NEW: `&cli.Command{` - -Compiler messages you might see: - -` -./commands.go:32:34: cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to -` - -#### cli.Flag changed - -`cli.Flag` is now a list of pointers. - -What this means to you: - -If you make a list of flags, add a `&` in front of each -item. cli.BoolFlag, cli.StringFlag, etc. - -* OLD: -` - app.Flags = []cli.Flag{ - cli.BoolFlag{ -` - -* NEW: -``` - app.Flags = []cli.Flag{ - &cli.BoolFlag{ -``` - -Compiler messages you might see: - -``` - cli.StringFlag does not implement cli.Flag (Apply method has pointer receiver) -``` - -#### Appending Commands - -Appending to a list of commands needs to be changed since the list is -now pointers. - -* OLD: `commands = append(commands, *c)` -* NEW: `commands = append(commands, c)` - -Compiler messages you might see: - -` -commands/commands.go:28:19: cannot use c (type *cli.Command) as type cli.Command in append -` - -#### Actions returns errors - -A command's `Action:` now returns an `error`. - -* OLD: `Action: func(c *cli.Context) {` -* NEW: `Action: func(c *cli.Context) error {` - -Compiler messages you might see: - -``` -./commands.go:35:2: cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value -``` - -#### Everything else - -Compile the code and worth through any errors it finds. Most should -relate to issues listed above. - -Once it compiles, test the command. Make sure `-h` displays help -properly, then try various flags and subcommands. - -If you find anything not covered by this document please let us know -by submitting a comment on -[Issue 921](https://github.com/urfave/cli/issues/921) -so that others can benefit. - ### Full API Example **Notice**: This is a contrived (functioning) example meant strictly for API From 9fd9cd1117d00d2d637cb0140b05cc3a47be685c Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sat, 4 Apr 2020 06:09:14 -0400 Subject: [PATCH 11/12] Link to migration guide --- README.md | 4 ++++ docs/v1/manual.md | 8 ++++++++ docs/v2/manual.md | 8 ++++++++ 3 files changed, 20 insertions(+) diff --git a/README.md b/README.md index ae9d19b068..408668bc3e 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,10 @@ Usage documentation exists for each major version. Don't know what version you'r - `v2` - [./docs/v2/manual.md](./docs/v2/manual.md) - `v1` - [./docs/v1/manual.md](./docs/v1/manual.md) +Guides for migrating to newer versions: + +- `v1-to-v2` - [./docs/migrate-v1-to-v2.md](./docs/migrate-v1-to-v2.md) + ## Installation Using this package requires a working Go environment. [See the install instructions for Go](http://golang.org/doc/install.html). diff --git a/docs/v1/manual.md b/docs/v1/manual.md index 51c5b72f3d..05ea37032e 100644 --- a/docs/v1/manual.md +++ b/docs/v1/manual.md @@ -27,6 +27,7 @@ cli v1 manual * [Version Flag](#version-flag) + [Customization](#customization-2) + [Full API Example](#full-api-example) + * [Migrating to V2](#migrating-to-v2) @@ -1476,3 +1477,10 @@ func wopAction(c *cli.Context) error { return nil } ``` + +## Migrating to V2 + +There are a small set of breaking changes between v1 and v2. +Converting is relatively straightforward and typically takes less than +an hour. Specific steps are included in +[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 71f5699917..750590c51d 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -3,6 +3,7 @@ cli v2 manual +- [Migrating From v1](#migrating-from-v1) - [Getting Started](#getting-started) - [Examples](#examples) * [Arguments](#arguments) @@ -38,6 +39,13 @@ cli v2 manual +## Migrating From Older Releases + +There are a small set of breaking changes between v1 and v2. +Converting is relatively straightforward and typically takes less than +an hour. Specific steps are included in +[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). + ## Getting Started One of the philosophies behind cli is that an API should be playful and full of From 2f5b961b06c4215ac9085f793eacd224a788a5f3 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sat, 4 Apr 2020 06:13:16 -0400 Subject: [PATCH 12/12] Link to migration guide --- docs/v2/manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 750590c51d..55008b4b55 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -3,7 +3,7 @@ cli v2 manual -- [Migrating From v1](#migrating-from-v1) +- [Migrating From Older Releases](#migrating-from-older-releases) - [Getting Started](#getting-started) - [Examples](#examples) * [Arguments](#arguments)