The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Depst-1.05
++
/ App::Depst

NAME

depst - Deployment State Manager

SYNOPSIS

depst COMMAND [DIR || NAME]

    depst init            # initialize depst for a project
    depst add DIR         # add a directory to depst tracking list
    depst rm DIR          # remove a directory from depst tracking list
    depst make NAME       # create a named template set (set of 3 files)
    depst list [NAME]     # dump a list of the template set (set of 3 files)
    depst status          # check status of tracked directories
    depst diff [NAME]     # display a diff of any modified actions
    depst clean           # reset depst state to match current files/directories
    depst preinstall      # set depst state so an "update" will deploy everything

    depst deploy NAME     # deployment of a specific action
    depst verify [NAME]   # verification of tracked actions or specific action
    depst revert NAME     # revertion of a specific action
    depst redeploy NAME   # deployment of a specific action
    depst revdeploy NAME  # revert and deployment of a specific action
    depst update          # automaticall deploy or revert to cause currency

    depst help            # display command synposis
    depst man             # display man page

DESCRIPTION

depst is a simple "deployment state" change management tool. I really like what Sqitch is doing, but I wanted something that worked on more than just databases. And I'm not very smart, so I wanted something really simple. (Both simple to use and simple to maintain.) Thus, depst was born.

Let's say you're working with a group of other software engineers on a particular software project using your favorite revision control system. Let's also say that you have a database that undergoes schema changes as features are developed, and you have various system activities like the installation of libraries or other applications. Then let's also say the team braches, works on stuff, shares those branches, reverts, merges, etc. And also from time to time you want to go back in time a bit so you can reproduce a bug. Maintaining the database state and the state of the system across all that activity can be problematic. depst tries to solve this in a very simple way, letting you be able to deploy, revert, and verify to any point in time in the development history.

COMMANDS

Typing just depst should bring up the usage instructions, which include a command list. In nearly all cases, depst assumes you are calling depst from the root directory of your project. If not, it will complain.

init

To start using depst, you need to initialize your project by calling init while in the root directory of your project. (If you are in a different directory, depst will assume that is your project's root directory.)

The initialization will result in a .depst directory being created. You'll almost certainly want to add ".depst" to your .gitignore file or whatever.

add DIR

Once a project has been initialized, you need to tell depst what directories you want to "track". Into these tracked directories you'll place subdirectories with recognizable names, and into each subdirectory a set of 3 files: deploy, revert, and verify.

For example, let's say you have a database. So you create db in your project's root directory. Then call depst add db from your root directory. Inside db, you might create the directory db/schema. And under that directory, add the files: deploy, revert, and verify.

The deploy file contains the instructions to create the database schema. The revert file contains the instructions to revert what the deploy file did. And the verify file let's you verify the deploy file worked.

rm DIR

This removes a directory from the depst tracking list.

make NAME

This is a helper command. Given a directory you've already added, it will create the subdirectory and deploy, revert, and verify files.

    # given db, creates db/schema and the 3 files
    depst make db/schema

As a nice helper bit, make will list the relative paths of the 3 new files. So if you want, you can do something like this:

    vi `depst make db/schema`

list [NAME]

If provided a name of an action, it does the last step of make. It lists out the relative paths of the 3 files, so you can do stuff like:

    vi `depst list db/schema`

If not provided a name of an action, it will list all tracked directories and every action within each directory.

status

This command will tell you your current state compared to what the current code says your state should be. For example, you might see something like this:

    diff - db
      + db/new_function
      - db/lolcats
      M db/schema/deploy
    ok - etc

depst will report for each tracked directory what are new changes that haven't yet been deployed (marked with a "+"), features that have been deployed in your current system state but are missing from the code (marked with a "-"), and changes to previously existing files (marked with an "M").

diff

This will display a diff delta of the differences of any modified action files. You can specify an optional name parameter that refers to a tracking directory, action name, or specific sub-action.

    depst diff
    depst diff db/schema
    depst diff db/schema/deploy

clean

Let's say that for some reason you have a delta between what depst thinks your system is and what your code says it ought to be, and you really believe your code is right. You can call clean to tell depst to just assume that what the code says is right.

preinstall

Let's say you're setting up a new system or installing the project/application, so you start by creating yourself a working directory. At some point, you'll want to deploy all the deploy actions. You'll need to init and add the directories/paths you need. But depst will have a cache that matches the current working directory. At this point, you need to preinstall to remove that cache and be in a state where you can update.

Here's an example of what you might want:

    depst init
    depst add path_to/stuff
    depst add path_to/other_stuff
    depst preinstall
    depst update

deploy NAME

This tells depst to deploy a specific action. For example, if you called status and got back results like in the status example above, you might then want to:

    depst deploy db/new_function

Note that you shouldn't add "/deploy" to the end of that. Also note that a deploy call will automatically call verify when complete.

verify [NAME]

This will run the verify step on any given action, or if no action name is provided, all actions under directories that are tracked.

Unlike deploy and revert files, which can run the user through all sorts of user input/output, verify files must return some value that is either true or false. depst will assume that if it sees a true value, verification is confirmed. If it receives a false value, verification is assumed to have failed.

revert NAME

This tells depst to revert a specific action. For example, if you deployed db/new_function but then you wanted to revert it, you'd:

    depst revert db/new_function

redeploy NAME

This is exactly the same as deploy, except that if you've already deployed an action, "redeploy" will let you deploy the action again, whereas "deploy" shouldn't.

revdeploy NAME

This is exactly the same as conducting a revert of an action followed by a deploy of the same action.

update

This will automatically deploy or revert as appropriate to make your system match the code. This will likely be the most common command you run.

If there are actions in the code that have not been deployed, these will be deployed. If there are actions that have been deployed that are no longer in the code, they will be reverted.

If there are actions that are in the code that have been deployed, but the "deploy" file has changed, then update will revert the previously deployed "deploy" file then deploy the new "deploy" file. (And note that the deployment will automatically call verify.)

help

Displays a synposis of commands and their usage.

man

Displays the man page for depst.

DEPENDENCIES

Sometimes you may have deployments (or revertions) that have dependencies on other deployments (or revertions). For example, if you want to add a column to a table in a database, that table (and the database) have to exist already.

To define a dependency, place the action's name after a depst.prereq marker, which itself likely will be after a comment. (The comment marker can be whatever the language of the deployment file is.) For example, in a SQL file that adds a column, you might have:

    -- depst.prereq: db/schema

WRAPPERS

Unless a "wrapper" is used (and thus, by default), depst will assume that the action files (those 3 files under each action name) are self-contained executable files. Often if not almost always the action sub-files would be a lot simpler and contain less code duplication if they were executed through some sort of wrapper.

Given our database example, we'd likely want each of the action sub-files to be pure SQL. In that case, we'll need to write some wrapper program that depst will run that will then consume and run the SQL files as appropriate.

depst looks for wrapper files up the chain from the location of the action file. Specifically, it'll assume a file is a wrapper if the filename is "depst.wrap". If such a file is found, then that file is called, and the name of the action sub-file is passed as its only argument.

As an example, let's say I created an action set that looked like this

    example/
        ls/
            deploy
            revert
            verify

Let's then also say that the example/ls/deploy file contains:

    ls

I could create a deployment file example/depst.wrap that looked like this:

    #!/bin/bash
    /bin/bash "$1"

Wrappers will only ever be run from the current code. For example, if you have a revert file for some action and you checkout your working directory to a point in time prior to the revert file existing, depst maintains a copy of the original revert file so it can revert the action. However, it will always rely on whatever wrapper is in the current working directory.

SEE ALSO

App::Sqitch.

AUTHOR

Gryphon Shafer <gryphon@cpan.org>.

  code('Perl') || die;

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.