# Retrospec plugin development

If you wish to automate the creation of a project or other project plugins you should
create a retrospec plugin. Follow the steps below to create a plugin.

## Creating a plugin using the plugin generator
1. Install the retrospec plugin that creates retrospec plugins!  `gem install retrospec-plugingen`
2. Come up with a name for you plugin.
3. Use the retrospec plugin help `retrospec -m /path_to_project/plugin_name plugingen -h`
4. Create the plugin `retrospec -m /path_to_project/plugin_name plugingen`
5. Open the /path_to_project/plugin_name in your favorite editor
6. Hack --> Test --> Publish

## Choosing a plugin name
By default the plugin generator will use the name of the directory or the name specified via the -n option.  This name
will used through the generator templates so its important to pick a sensible name.  The generator also uses the plugin_name
as a class name although you are free to change it after creation. 

### Naming the gem and repo
Please ensure the gem name uses the following naming scheme retrospec-plugin_name and that your repo is also named retrospec-plugin_name.
This will help everyone identify what the repo and gem do more easily. 

Note: puppet-retrospec does not follow this standard due to a legacy name issue that would have caused confusion.

## What you need to override
* run

## Create a context object
By default the plugin generator will create a context object that can be used inside templates.  The default context object
does not contain anything useful so you will want to customize this object only if your templates require variable interpolation.

## Add custom options to the cli
You can get input from the user in the form of cli options.  These options are passed in directly to your init method.
To customize these options please override the the following class method:

```
def self.cli_options(global_opts)
  Trollop::options do
    opt :option1, "Some fancy option"
  end
end
```

See the [trollop documentation](http://trollop.rubyforge.org) for more info.

## Module helpers
The module helpers module is included by default and contains useful methods to safely create files. When creating files
use the safe create methods in order to protect the users content from being overwritten.  
For a list of methods please see the [source code](https://github.com/nwops/retrospec/blob/master/lib/retrospec/plugins/v1/module_helpers.rb)