Add a v1 => v2 migration guide

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

docs/migrate-v1-to-v2.md

@@ -0,0 +1,176 @@
+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.
+
+<!-- toc -->
+
+  * [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)
+
+<!-- tocstop -->
+
+# 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.
+
+# 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
+```
+
+# 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)
+```
+
+# 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
+```
+
+# 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
+
+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.

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)
 
 <!-- tocstop -->
 
@@ -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).

docs/v2/manual.md

@@ -3,6 +3,7 @@ cli v2 manual
 
 <!-- toc -->
 
+- [Migrating From Older Releases](#migrating-from-older-releases)
 - [Getting Started](#getting-started)
 - [Examples](#examples)
   * [Arguments](#arguments)
@@ -38,6 +39,13 @@ cli v2 manual
 
 <!-- tocstop -->
 
+## 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