From 84c98fac3efcfcc289b9046400d470c602c22b56 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Tue, 31 Mar 2020 18:53:45 -0400 Subject: [PATCH] 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 0000000..4bb676c --- /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 eab76d8..2244f0c 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.