heroku style guide

TODO empty arrays and/or nil values (see apps:info)

General Guidelines

Use full sentences, including punctuation.
Labels should be provided where needed in the form of 'Labels labels:'.
Commands should have one newline between the header and body and another after the body.
Alpha-sort arrays before display and display labeled data in alpha-sorted key order.

Arguments, Flags and User Input

Include the name of parameters, in ALLCAPS when describing their usage.
Include flags surrounded by single quotes when describing their usage.

When including a value user input, surround it with double quotes.

  $ heroku create new_name -s invalid_stack
  -> Creating app 'new_name'... failure

     Error: 'invalid_stack' is not a valid STACK argument for '-s'.

Additional flags and arguments that would be ignored should raise an error.

  $ heroku create new_name -foo bar
  -> Creating app 'new_name'... failure

     Error: '-foo' is not a recognized flag.

Commands

There are two primary activities when using the api.
Active commands attempt an action, display work in progress, and return success or failure.
Informative commands simply return the requested information.
Errors and warnings should use the the appropriate guidelines as set forth later in this document.

Active Commands

The actual action should display a 'ing' type message, which then displays eit... success... failure.

  $ heroku create foo-9999
  -> Creating app 'foo-9999'... success

     Git URL:
       [email protected]/foo-999.git
     Stack:
       bamboo-mri-1.9.2
     Web URL:
       http://foo-9999.herokuapp.com

  $ heroku create foo-9999
  -> Creating app 'foo-9999'... failure

     Error: An app with NAME 'existing_name' already exists.

  $ heroku create new_name -s invalid_stack
  -> Creating app 'new_name'... failure

     Error: 'invalid_stack' is not a valid STACK argument for '-s'.

Informative Commands:

First line should describe what information will follow, in a full sentence, with properly quoted and ALLCAPS any arguments.
Each datapoint should be labeled, either by the overall header or by it's purpose.
Each datapoint should appear on it's own line.
Multiple datapoints can appear under the same label, in which case each should appear on it's own line.

Lists of labeled datasets should be displayed in a table format.

  $ heroku domains
  -> Domain names for 'example':

     example.com
     example.heroku.com
     www.example.com

  $ heroku apps:info
  -> Info for 'example':

     Addons:
       Custom Domains
       Shared Database 5MB
     Data size:
       (empty)
     Domain name:
       http://example.com/
     Dynos:
       1
     Git repo:
       [email protected]:example.git
     Owner:
       [email protected]
     Repo size:
       2M
     Slug size:
       2M
     Stack:
       cedar
     Web URL:
       http://example.heroku.com/
     Workers:
       0

  $ heroku ps
  -> Processes for 'example':

     Process       State               Command
     ------------  ------------------  ------------------------------
     web.1         idle for 3h         thin -p $PORT -e $RACK_ENV -R $HER..

Errors

Each error should be on its own line, starting with 'Error: ', followed by a complete sentence explaining the error.

Any associated arguments or parameters should be called out in ALLCAPS in the explanation.

$ heroku create existing_name
-> Creating 'existing_name'... failure

   Error: An app with NAME 'existing_name' already exists.

$ heroku create new_name -s invalid_stack
-> Creating 'new_name'... failure

   Error: 'invalid_stack' is not a valid STACK argument for '-s'.

Help

Top level help should provide an overview of all help topics.
```
  $ heroku help
  ...
```

Help for a namespaces should list the descriptions of top level commands.

  $ heroku help run
  -> Run an attached process.

     Additional commands, type `heroku help COMMAND` for more details:
       run:console [COMMAND]
         Open remote console session, optionally running COMMAND.
       run:rake COMMAND
         Remotely execute COMMAND with rake.

If the namespace also implicitly runs a command, flags and suggested usage should be provided.

  $ heroku help apps
  -> List all of your apps.

     Additional commands, type `heroku help COMMAND` for more details:
       apps:create [NAME]
         Create a new app, optionally specifying a NAME.
       apps:destroy
         Permanently destroy app.
       apps:info
         Show detailed app information.
       apps:open
         Open app in a web browser.
       apps:rename NEWNAME
         Rename app to NEWNAME.

     You should try:
       heroku apps

Help for specific commands should describe purpose, outline flags and provide suggested usage.

  $ heroku help apps:create
  -> Create a new app, optionally specifying a NAME.

     Flags:
      --addons ADDONS
        Comma-delimited list of ADDONS to install.
      -r, --remote REMOTE
        The git REMOTE to create, defaults to 'heroku'.
      -s, --stack  STACK
        The STACK on which to create the app.

     You should try:
       heroku apps:create [NAME]

Suggestions

When the user should run a different command instead, provide a suggestion.

Suggestions should start with "You should try:\n" and have an indented command that can be copy/pasted on the following line.

  $ heroku non_command
  -> Error: 'non_command' is not a known command.

     You should try:
       heroku help

  $ heroku app
  -> Error: 'app' in not a known command.

     You should try:
       heroku apps

Warnings

When there is something that a user should be aware of, but for which no error has occured, you should utilize a warning.
Each warning should be on its own line, starting with 'Warning: ', followed by a complete sentence explaining the warning.