Overview: User's Perspective

Core Features

• Well structured, informative output.
• Nicely managed and natural-feeling fallback to manual execution of unmapped steps.
• Fully logged sessions.
• Commandline or web-based experience.
• How2 files can be referenced from the local filesystem or a web url.
• Step files can be referenced from the local filesystem or a GitHub repo.
• Configuration can be saved for later executions.

Usage

how2 
  --experience web|cli            # choose the user experience interface
  --log-text /path/to/log.txt     # markdown-compatible log of session
  --log-html /path/to/log.html    # pretty and interactive html log of session
  --config /path/to/config.yml    # config file to load session settings
  --help                          # this help message
  
  options when using --experience web
  --listen ip:port                # listen on a specified port to allow using
                                  # the html experience remotely
  --no-launch-browser             # do not automatically launch the browser

Proposed Sample Commandline Experience Transcript

Given this set of contrived how2 files:

~/how2/deploy_the_suite.how2

1. Disable the suite
2. Stop all the services
   1. Stop the MyService service on TheMachineName
   2. Stop the AnotherService service on AnotherMachine

~/how2/disable_the_suite.how2

1. Switch to the disabled site:
     server: MyServer
     live site name: LiveSite
     disabled site name: DisabledSite
2. Stand on your head
3. Verify that the disabled site is up

This is what I imagine the CLI experience may be like. This transcript assumes that there are no saved settings, that there is a mixture of manual and automated steps, and that some steps will fail. In all, it is a bit chatty, though coloring in the terminal, where available, may help to provide additional contextual separation. Lines beginning with a * are simply noting something that happens outside of the CLI.

$ how2
Where are the how2 files you would like to use?
> ~/how2/
What would you like to do?
  1) Deploy the Suite
  2) Disable the Suite
> depl<Tab>
==================
Beginning the How2
==================
1. Disable the suite
   1. Switch to the disabled site ... ok
   2. Stand on your head (manual)
 
You will need to Stand on your head manually
  Notes: optional notes from a runner marked as manual

Was it successful? yes/no
> yes
Is there any output that should be logged? yes/no
> yes
 * launches editor to enter log blob

   3. Verify that the disabled site is up ... missing information

I need to know the "suite url" to Do step 3
  Notes: _optional note from the runner_
> http://www.suite.com
  Continuing to Verify that the disabled site is up ... ok

2. Stop all the services
   1. Stop the MyService service on TheMachineName ... failed

Stop the MyService service on TheMachineName failed.
Do you want to edit/ammend the logged output? yes/no
> yes
 * launches editor with captured output prefilled 
Do you want to continue the how2 or abort? continue/abort
> continue

  Stop the second service (manual)

You will need to Stop the AnotherService service on AnotherMachine manually

Was it successful? yes/no
> no
 * launches editor to enter log blob
Do you want to continue the how2 or abort? continue/abort
> abort
What report type would you like? text/html/none
> text
Where? [deploy_the_suite_20120613_1234.log]
> deploy.log
Log written. Goodbye.
$

deploy.log

Deploy the Suite
-----------------
Started: Date/Time    Status: Failed
Ended: Date/Time
-----------------
1. Disable the suite ..................................... ok
   a. Do step 1 .......................................... ok
      Some captured output of step 1
   b. Do step 2 .......................................... ok (manual)
   c. Do step 3 .......................................... ok (added "suite url" to environment settings)
2. Stop all services ..................................... failed
   a. Stop the MyService service on TheMachineName ....... failed
      Windows Exception: Unable to stop service. File locked.
   b. Stop the AnotherService service on AnotherMachine .. failed
      Windows Exception: Unable to stop service. File locked.

How2 aborted due to step failure