4teamwork/ftw.upgrade — pull request #57 by jone (2014-12-06 11:12:16+00:00)
Title: Command line tool for creating upgrades

Closes #56

- Adds a new `bin/upgrade` console script.
- Adds a `bin/upgrade create [-h] [--path upgrades-directory] title` command for creating upgrade steps.
- Adds a `bin/upgrade touch [-h] [--after path] [--before path] path` for changing upgrade steps order.
- Adds a `create-upgrade` for copying into the `PATH`.

#### upgrade script
The upgrade script provides commands (currently only `create` and `touch`) and will be extended with API things, such as installing upgrades from the command line.

#### create command
```
$ /bin/upgrade create --help
usage: ./bin/upgrade create [-h] [--path upgrades-directory] title

The "create" command creates a new upgrade step in the "upgrades" directory of
this package. The created upgrade step works only when the "upgrades"
directory is registered using the "upgrade-step:directory" directive in ZCML.
The command creates a new directory within the "upgrades" directory and adds a
"upgrade.py" file with a default upgrade step. The "title" argument is used
for naming the directory as well as the upgrade step class in the generated
"upgrade.py" file.

positional arguments:
title Title of the upgrade step. Either in camel case or
with underscores.

optional arguments:
-h, --help show this help message and exit
--path upgrades-directory, -p upgrades-directory
Path to the upgrades directory. The default path is
searched by resolving the top level in the egg-info
and looking for an "upgrades" directory. If no egg-
info is found or there is no or multiple "upgrades"
directories, the user has to provide the path
explicitly.
```

Examples:

```
$ bin/upgrade create AddControlpanelAction
$ bin/upgrade create --path my/package/upgrades/default update_workflow
```

#### touch command
```
$ ./bin/upgrade touch --help
usage: ./bin/upgrade touch [-h] [--after path] [--before path] path

Updates the timestamp of an existing upgrade step. This is useful for changing
the order of upgrade steps.

positional arguments:
path Path to the upgrade step directory to touch.

optional arguments:
-h, --help show this help message and exit
--after path, -a path
Move after this upgrade step directory.
--before path, -b path
Move before this upgrade step directory.
```

Examples:
```
$ bin/upgrade touch upgrades/20141218093045_add_controlpanel_action
$ bin/upgrade touch 20141218093045_add_controlpanel_action --before 20141220181500_update_registry
$ bin/upgrade touch 20141218093045_add_controlpanel_action --after 20141220181500_update_registry
```

#### create-upgrade script
The script is located at `scripts/create-upgrade` in the ftw.upgrade repository.
The idea is that it can be copied somewhere into the `PATH` on the developer machine.
This allows the developer to run e.g. `create-upgrade UpdateWorkflow` anywhere within a buildout directory (with a `bin/upgrade` command).
All arguments are passed to `bin/upgrade create`, additionally ``--path `pwd``` is added.