octocatalog-diff 0.5.1

data/doc/basic.md

@@ -0,0 +1,70 @@
+# Basic usage
+
+The most basic usage of octocatalog-diff is to compare catalogs built from two different git branches, for a node of your choosing.
+
+You should be aware of these defaults, all of which are [configurable](/doc/configuration.md).
+
+- octocatalog-diff will default to compiling catalogs based on the assumption that your Puppet code resides in a git repository. If your Puppet code does not reside in a git repository, head over to the [advanced instructions](/doc/advanced.md) for workarounds.
+
+- octocatalog-diff will compile the catalog produced from the `origin/master` branch of your repository as the "from" catalog, and the catalog produced from your current working directory as the "to" catalog. You can override these defaults with the `-f BRANCH` and `-t BRANCH` arguments, for the "from" and "to" branches, respectively.
+
+- octocatalog-diff will assume you are not using hiera or an external node classifier, unless you [configure](/doc/configuration.md) it accordingly, or use the appropriate command line arguments to point it at your hiera configuration and/or ENC script.
+
+You are required to provide the following information, either as a command line argument, in the [configuration](/doc/configuration.md), or in some cases, via the environment:
+
+- The node name whose catalogs you wish to compile. Use `-n HOSTNAME` on the command line.
+
+- Facts, which can either be retrieved from [PuppetDB](/doc/configuration-puppetdb.md) or via the `--fact-file` command line option. See the usage examples below.
+
+## Examples
+
+### From git repository with facts from PuppetDB
+
+```
+export PUPPETDB_URL="http://puppetdb.yourdomain.com:8080"
+cd Puppet_Checkout_Directory
+git checkout master
+git pull
+octocatalog-diff -n SomeNodeName.yourdomain.com
+```
+
+### Using a fact file
+
+You can retrieve the fact file from your Puppet Master (3.x) typically in `/var/lib/puppet/yaml/facts/<node>.yaml`, or your Puppet Server (4.x) typically in `/opt/puppetlabs/server/data/puppetserver/yaml/facts/<node>.yaml`. We recommend using PuppetDB as a more convenient fact source, but you can copy the fact file for a node from your Puppet server onto the machine running octocatalog-diff for testing purposes.
+
+```
+# Copy the fact file for SomeNodeName.yourdomain.com into /tmp/SomeNodeName.yourdomain.com.yaml
+cd Puppet_Checkout_Directory
+git checkout master
+git pull
+octocatalog-diff -n SomeNodeName.yourdomain.com --fact-file /tmp/SomeNodeName.yourdomain.com.yaml
+```
+
+## Using hiera
+
+This example demonstrates how to point octocatalog-diff at your Hiera configuration file. The Hiera configuration file for your site might be found in `/etc/puppet/hiera.yaml` (for Puppet 3.x) or `/etc/puppetlabs/puppet/hiera.yaml` (for Puppet 4.x).
+
+Note that you will either need to configure the PuppetDB URL or specify a `--fact-file` for this to work.
+
+```
+# Copy the fact file for SomeNodeName.yourdomain.com into /tmp/SomeNodeName.yourdomain.com.yaml
+# (or)
+# Set the PUPPETDB_URL variable as shown in the first example
+#
+# Also copy hiera.yaml from your Puppet master into the /tmp directory
+
+cd Puppet_Checkout_Directory
+git checkout master
+git pull
+octocatalog-diff -n SomeNodeName.yourdomain.com --hiera-config /tmp/hiera.yaml
+```
+
+Depending on your hiera configuration, you may also need to supply the `--hiera-path-strip` option (or set that option in your [configuration](/doc/configuration.md)). Consult the [configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md) document for details on this option.
+
+## Next steps
+
+If you're ready to learn about additional command line flags to customize your experience, head to [Advanced usage](/doc/advanced.md).
+
+If you experience problems running octocatalog-diff even with these most basic arguments, please see [Troubleshooting](/doc/troubleshooting.md).
+
+If you are not using git to manage your Puppet source code, you will need to see the [Advanced usage](/doc/advanced.md) instructions to get your directories manually bootstrapped for use, or use one of the other supported methods to build catalogs.

data/doc/configuration-enc.md

@@ -0,0 +1,69 @@
+# Configuring octocatalog-diff to use ENC
+
+If you use an [External Node Classifier (ENC)](https://docs.puppet.com/guides/external_nodes.html) on your Puppet master, you should configure octocatalog-diff to use the same ENC when it compiles catalogs.
+
+Before you start, please understand how octocatalog-diff compiles a catalog:
+
+- It creates a temporary directory (e.g. `/var/tmp/puppet-compile-dir-92347829847`)
+- It copies or creates hiera configuration, ENC, PuppetDB configuration, etc., in the temporary directory
+- It symlinks `/var/tmp/puppet-compile-dir-92347829847/environments/production` to your code
+- It compiles the catalog, based on the temporary directory, for environment=production
+- It removes the temporary directory
+
+NOTE: If you are using the built-in node classification in Puppet Enterprise, you don't need to worry about any of this. Instead, please read about [Puppet Enterprise as your ENC](/doc/advanced-pe-enc.md).
+
+## Configuring the path to the ENC
+
+The command line option `--enc PATH` allows you to set the path to your ENC script.
+
+You may specify this as either an absolute or a relative path.
+
+- As a relative path
+
+  octocatalog-diff knows to use a relative path when the supplied path for `--enc` does not start with a `/`.
+
+    ```
+    bin/octocatalog-diff --enc config/enc.sh ...
+    ```
+
+  The path is relative to a checkout of your Puppet repository. As per the example in the introduction, say that octocatalog-diff is using a temporary directory of `/var/tmp/puppet-compile-dir-92347829847` when compiling a Puppet catalog. With the setting above, it will copy `config/enc.sh` (relative to your Puppet checkout) into the temporary directory.
+
+  If you are specifying the ENC path in the [configuration file](/doc/configuration.md), you will instead set the variable like this:
+
+    ```
+    settings[:enc] = 'config/enc.sh'
+    ```
+
+  octocatalog-diff will fail if you specify a ENC location that cannot be opened.
+
+- As an absolute path
+
+  octocatalog-diff knows to use a relative path when the supplied path for `--enc` starts with a `/`.
+
+  For example:
+
+    ```
+    bin/octocatalog-diff --enc /etc/puppetlabs/puppet/enc.sh ...
+    ```
+
+  If you are specifying the ENC path in the [configuration file](/doc/configuration.md), you will instead set the variable like this:
+
+    ```
+    settings[:enc] = '/etc/puppetlabs/puppet/enc.sh'
+    ```
+
+  Please note that octocatalog-diff will copy the file from the specified location into the compile directory. Since this ENC file is not copied from your Puppet repo, there is no way to compile the "to" and "from" branches using different ENC scripts. Furthermore, you are responsible for getting this file into place on any machine that will run octocatalog-diff.
+
+  We strongly recommend that you version-control your ENC script within your Puppet repository, and use the relative path option described above.
+
+## Executing the ENC
+
+When Puppet runs the ENC, it will do so with one argument (the node name for which you are compiling the catalog).
+
+For example, when compiling the catalog for `some-node.github.net`, Puppet will effectively execute this command:
+
+  ```
+  /etc/puppetlabs/puppet/enc.sh some-node.github.net
+  ```
+
+Sometimes the ENC script requires credentials or makes other assumptions about the system on which it is running. To be able to run the ENC script on systems other than your Puppet master, you will need to ensure that any such credentials are supplied and other assumptions are met.

data/doc/configuration-hiera.md

@@ -0,0 +1,103 @@
+# Configuring octocatalog-diff to use Hiera
+
+If you are using Hiera with Puppet, then you must already have a [`hiera.yaml`](https://docs.puppet.com/puppet/latest/reference/config_file_hiera.html) file to configure it. These instructions will guide you through pointing octocatalog-diff at that configuration file.
+
+Before you start, please understand how octocatalog-diff compiles a catalog:
+
+- It creates a temporary directory (e.g. `/var/tmp/puppet-compile-dir-92347829847`)
+- It copies or creates hiera configuration, ENC, PuppetDB configuration, etc., in the temporary directory
+- It symlinks `/var/tmp/puppet-compile-dir-92347829847/environments/production` to your code
+- It compiles the catalog, based on the temporary directory, for environment=production
+- It removes the temporary directory
+
+## Configuring the path to hiera.yaml
+
+The command line option `--hiera-config PATH` allows you to set the path to hiera.yaml.
+
+You may specify this as either an absolute or a relative path.
+
+- As a relative path
+
+  octocatalog-diff knows to use a relative path when the supplied path for `--hiera-config` does not start with a `/`.
+
+    ```
+    bin/octocatalog-diff --hiera-config config/hiera.yaml ...
+    ```
+
+  The path is relative to a checkout of your Puppet repository. As per the example in the introduction, say that octocatalog-diff is using a temporary directory of `/var/tmp/puppet-compile-dir-92347829847` when compiling a Puppet catalog. With the setting above, it will copy `config/hiera.yaml` (relative to your Puppet checkout) into the temporary directory.
+
+  If you use Puppet to manage your hiera.yaml file on Puppet masters, perhaps it is found in one of the modules in your code. In that case, you may use syntax like:
+
+    ```
+    bin/octocatalog-diff --hiera-config modules/puppet/files/hiera.yaml ...
+    ```
+
+  If you are specifying the hiera.yaml path in the [configuration file](/doc/configuration.md), you will instead set the variable like this:
+
+    ```
+    settings[:hiera_config] = 'config/hiera.yaml'
+    settings[:hiera_config] = 'modules/puppet/files/hiera.yaml'
+    ```
+
+  octocatalog-diff will fail if you specify a hiera configuration location that cannot be opened.
+
+- As an absolute path
+
+  octocatalog-diff knows to use a relative path when the supplied path for `--hiera-config` starts with a `/`.
+
+  For example:
+
+    ```
+    bin/octocatalog-diff --hiera-config /etc/puppetlabs/puppet/hiera.yaml ...
+    ```
+
+  If you are specifying the hiera.yaml path in the [configuration file](/doc/configuration.md), you will instead set the variable like this:
+
+    ```
+    settings[:hiera_config] = '/etc/puppetlabs/puppet/hiera.yaml'
+    ```
+
+  Please note that octocatalog-diff will copy the file from the specified location into the compile directory. Since this hiera.yaml file is not copied from your Puppet repo, there is no way to compile the "to" and "from" branches using different hiera.yaml files. Furthermore, you are responsible for getting this file into place on any machine that will run octocatalog-diff.
+
+  We strongly recommend that you version-control your hiera.yaml file within your Puppet repository, and use the relative path option described above.
+
+## Configuring the prefix path to strip
+
+The command line option `--hiera-path-strip PATH` allows you to manipulate directory paths for the JSON or YAML hiera backends. This setting only has an effect on the copy of hiera.yaml that is copied into the temporary compilation directory. This does not make any changes to the actual source hiera.yaml file on your system or in your checkout.
+
+For example, perhaps your production hiera.yaml file has entries such as the following:
+
+```
+:backends:
+  - yaml
+:yaml:
+  :datadir: /var/lib/puppet/environments/%{::environment}/hieradata
+:hierarchy:
+  - servers/%{::fqdn}
+  - platform/%{::virtual}
+  - datacenter/%{::datacenter}
+  - os/%{::operatingsystem}
+  - common
+```
+
+However, when you run octocatalog-diff, the hiera data will not actually be found in `/var/lib/puppet/environments/production/hieradata`, but rather in a directory called `environments/production/hieradata` relative to the checkout of your Puppet code.
+
+Specifying `--hiera-path-strip PATH` causes octocatalog-diff will rewrite the datadir for the YAML and JSON configuration. In the example above, the correct setting is `--hiera-path-strip /var/lib/puppet`, which will result in the following configuration in the hiera.yaml file:
+
+```
+bin/octocatalog-diff --hiera-config environments/production/config/hiera.yaml --hiera-path-strip /var/lib/puppet
+```
+
+```
+# This is the temporary hiera.yaml file used for octocatalog-diff catalog compilation
+:backends:
+  - yaml
+:yaml:
+  :datadir: /var/tmp/puppet-compile-dir-92347829847/environments/%{::environment}/hieradata
+:hierarchy:
+  - servers/%{::fqdn}
+  - platform/%{::virtual}
+  - datacenter/%{::datacenter}
+  - os/%{::operatingsystem}
+  - common
+```

data/doc/configuration-puppetdb.md

@@ -0,0 +1,49 @@
+# Configuring octocatalog-diff to use PuppetDB
+
+octocatalog-diff can interact with PuppetDB in the following ways:
+
+- Retrieving the most recent set of facts for a node
+- Query for exported resources during a Puppet run with storeconfigs enabled
+- Retrieving a catalog for a node
+
+For this to work, you will need to configure or provide information about your PuppetDB server to octocatalog-diff. You can provide this information via a [configuration file](/doc/configuration.md), via environment variables, or via command line parameters.
+
+## Required information
+
+- **Version of PuppetDB**: octocatalog-diff supports PuppetDB's query API v4, which requires that you be running PuppetDB 2.3 or higher.
+
+- **URL to PuppetDB**: This is the URL with the host name and port number to reach your PuppetDB instance. If you have already set up your Puppet master to communicate with PuppetDB, you can see the URL by reviewing `/etc/puppetlabs/puppet/puppetdb.conf` (on Puppet Server) or `/etc/puppet/puppetdb.conf` (on Puppet Master 3.x). The URL (or URLs) to your PuppetDB installation are visible in the `server_urls` configuration setting.
+
+- **SSL Authentication Information**: Whether your PuppetDB instance requires clients to authenticate via SSL certificates. Unless you have made a special effort to configure your PuppetDB instance not to require client certificates, it is likely that client certificate authentication is required.
+
+## Supplying necessary information via configuration files
+
+The following settings can be used in a [configuration file](/doc/configuration.md).
+
+| Setting | Description |
+| --- | --- |
+| `settings[:puppetdb_url]` | PuppetDB URL settings. If this is a string, it will set a single PuppetDB URL. If it is an array, it will set multiple URLs, which will be tried in a random order until one responds. |
+| `settings[:puppetdb_ssl_ca]` | Path to the certificate of the CA that signed PuppetDB's certificate. This file is typically found in `/etc/puppetlabs/puppetdb/ssl/ca.pem` on your PuppetDB server. This file should contain only the public certificate, so it is safe to distribute to developer workstations or CI environments. |
+| `settings[:puppetdb_ssl_client_cert]` | Path to the certificate of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the certificate from your PuppetDB server itself. |
+| `settings[:puppetdb_ssl_client_key]` | Path to the private key of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the private key from your PuppetDB server itself. |
+| `settings[:puppetdb_ssl_client_password]` | Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required and should be left undefined. |
+
+## Supplying necessary information via the command line
+
+The following arguments can be used on the command line.
+
+| Setting | Description |
+| --- | --- |
+| --puppetdb-url https://puppetdb.example.net:8081 | PuppetDB URL. The argument should match the `server_urls` configuration setting as described previously. Please note that only one URL is supported via the command line method, so if you have multiple `server_urls` URLs specified, you can only choose one. To use multiple URLs for failover purposes, please configure via configuration files. |
+| --puppetdb-ssl-ca FILENAME | Path to the certificate of the CA that signed PuppetDB's certificate. This file is typically found in `/etc/puppetlabs/puppetdb/ssl/ca.pem` on your PuppetDB server. This file should contain only the public certificate, so it is safe to distribute to developer workstations or CI environments. |
+| --puppetdb-ssl-client-cert FILENAME | Path to the certificate of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the certificate from your PuppetDB server itself. |
+| --puppetdb-ssl-client-key FILENAME | Path to the private key of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the private key from your PuppetDB server itself. |
+| --puppetdb-ssl-client-password PASSWORD_STRING | Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required. |
+
+## Supplying necessary information via the environment
+
+:warning: While this method of configuring octocatalog-diff for use with PuppetDB is currently supported, we recommend that configuration is done via the command line or in configuration files.
+
+Set the environment variable `PUPPETDB_URL` to match the `server_urls` configuration setting as described previously. Please note that only one URL is supported via the environment variable method, so if you have multiple `server_urls` URLs specified, you can only choose one. To use multiple URLs for failover purposes, please configure via configuration files.
+
+Environment variable support is not currently available for SSL client authentication settings.

data/doc/configuration.md

@@ -0,0 +1,51 @@
+# Configuration
+
+`octocatalog-diff` may require configuration to work correctly with your Puppet setup.
+
+0. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories.
+
+  - In the base directory of your Puppet repository checkout (i.e., your current working directory):
+
+    ```
+    .octocatalog-diff.cfg.rb
+    ```
+
+  - In your home directory:
+
+    ```
+    $HOME/.octocatalog-diff.cfg.rb
+    ```
+
+  - In one of the following system locations:
+
+    ```
+    /usr/local/etc/octocatalog-diff.cfg.rb
+    /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb
+    /etc/octocatalog-diff.cfg.rb
+    ```
+
+  Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish.
+
+0. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration.
+
+  To be minimally functional, you will almost certainly need to define at least the following settings:
+
+  - `settings[:hiera_yaml_file]` as the absolute or relative path to your hiera configuration file
+  - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file
+  - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained
+
+  For more information on these settings:
+
+  - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md)
+  - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md)
+  - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md)
+
+0. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof.
+
+  ```
+  octocatalog-diff --config-test
+  ```
+
+  Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed.
+
+Now that you have entered your configuration and confirmed proper reading of your configuration file, proceed to [Basic usage](/doc/basic.md) to see if it works!

data/doc/dev/README.md

@@ -0,0 +1 @@
+# octocatalog-diff developer documentation

data/doc/dev/coverage.md

@@ -0,0 +1,34 @@
+# Test coverage
+
+We provide two types of tests for octocatalog-diff:
+
+  - Unit tests (found in [/spec/octocatalog-diff/tests](/spec/octocatalog-diff/tests))
+  - Integration tests (found in [/spec/octocatalog-diff/integration](/spec/octocatalog-diff/integration))
+
+The difference between these is as follows. Unit tests are designed to test the smallest bit of code that's practical to test. Integration tests are designed to run from end-to-end, starting via the invocation from the command line, exercising internals, and checking output from the end result.
+
+It's our goal to have as much test coverage as we can provide from both sides, so that we can have confidence in anything we release.
+
+## Coverage report
+
+The `simplecov` gem is bundled with octocatalog-diff to produce coverage reports.
+
+To build a coverage report for unit tests only:
+
+  ```
+  rake coverage:spec
+  ```
+
+To build a coverage report for integration tests only:
+
+  ```
+  rake coverage:integration
+  ```
+
+To build a coverage report combining the results of unit tests and integration test:
+
+  ```
+  rake coverage:all
+  ```
+
+Running any of these tests creates a `coverage` directory in the root of the project, and this contains an `index.html` file with a graphical report. Open this file in a browser to see the results.

data/doc/dev/how-to-add-options.md

@@ -0,0 +1,83 @@
+# How to add new command line options
+
+This document contains a checklist and guidance to adding new command line options.
+
+## Checklist
+
+Please copy and paste this text into your Pull Request. This will create boxes for each step along the way, which you can then check off when complete.
+
+```
+- [ ] REQUIRED: Add new file in `lib/octocatalog-diff/catalog-diff/cli/options`
+- [ ] REQUIRED: Add corresponding test in `spec/octocatalog-diff/tests/catalog-diff/cli/options`
+- [ ] OPTIONAL: Add default value in `lib/octocatalog-diff/catalog-diff/cli.rb`
+- [ ] OPTIONAL: Add configuration example in `examples/octocatalog-diff.cfg.rb`
+- [ ] REQUIRED: Add code to implement your option in `lib`
+- [ ] REQUIRED: Add corresponding tests for code to implement your option in `spec/octocatalog-diff/tests`
+- [ ] OPTIONAL: Add an integration test to test your option in `spec/octocatalog-diff/integration`
+```
+
+## Procedure
+
+### Create option parser
+
+Option parsers are created in [`lib/octocatalog-diff/catalog-diff/cli/options`](/lib/octocatalog-diff/catalog-diff/cli/options).
+
+Your option should have a "long form" that contains dashes and not underscores. For example, you should prefer `--your-new-option` and NOT use `--your_new_option`.
+
+The file you create should reflect the name of your option. Generally the file name is the command line flag, with `-` converted to `_`.
+
+The key that your option creates in the options hash should generally be a symbol, named the same as the command line flag, with `-` converted to `_`. In this example, `:your_new_option`.
+
+If you are creating a binary (yes-no) option, please recognize both `--your-new-option` and `--no-your-new-option`.
+
+We recommend copying prior art as a template:
+
+- For a binary (yes-no) option, look at [`quiet.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/quiet.rb).
+
+- For an option that takes an integer parameter, look at [`retry_failed_catalog.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/retry_failed_catalog.rb).
+
+- For an option that takes an string parameter, look at [`bootstrap_script.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_script.rb).
+
+- For an option that takes an array or can be specified more than once, look at [`bootstrap_environment.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_environment.rb).
+
+If you can do simple validation of the argument, such as making sure the argument (if specified) matches a particular regular expression or is one of a particular set of values, please do that within the option file. For example, look at [`facts_terminus.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/facts_terminus.rb).
+
+### Create test for option parser
+
+Option parser tests are created in [`spec/octocatalog-diff/tests/catalog-diff/cli/options`](/spec/octocatalog-diff/tests/catalog-diff/cli/options).
+
+If you used an existing option as a reference for your new code, consider using that option's test as a reference for your test. We have some methods, e.g. `test_with_true_false_option`, to avoid repetitive code for common patterns.
+
+If you have handled any edge cases, e.g. input validation, please add a test that expects an error when input is provided that does not match your validation. For example, look at [`parser_spec.rb`](/spec/octocatalog-diff/tests/catalog-diff/cli/options/parser_spec.rb).
+
+### Add default value (OPTIONAL)
+
+Unless specifically cleared with the project maintainers, adding a new option should not change the behavior of the program when that option isn't specified, and the new option should not be required.
+
+In other words, if someone invokes the program *without* specifying your option, it should behave in the same way as it did before your option was ever added.
+
+If you need to set a default value for your option, do so in [`lib/octocatalog-diff/catalog-diff/cli.rb`](/lib/octocatalog-diff/catalog-diff/cli.rb). Items should be added to DEFAULT_OPTIONS *only if* a value is required even if your option is not provided, or if you are defaulting something to *true* but providing an option to make it false.
+
+### Add configuration example (OPTIONAL)
+
+If you believe your option is of general use to other users of octocatalog-diff such that they may wish to add it to their configuration file, update [`examples/octocatalog-diff.cfg.rb`](/examples/octocatalog-diff.cfg.rb) with some comments and example code for your option.
+
+Only the most commonly used options have entries in the example configuration file. If you are unsure whether or not to include your option there, please [open an issue](https://github.com/github/octocatalog-diff/issues/new) to discuss.
+
+As described in the default value section above, if your option is not configured in the template, the program should still work as it did before your new option was added. We want to avoid forcing users to update their configuration file unless there is a major update.
+
+### Add code to implement your option
+
+This is for you to figure out! :smile_cat:
+
+### Add corresponding tests for code
+
+Please add unit tests in [`spec/octocatalog-diff/tests`](/spec/octocatalog-diff/tests) that test the new behavior of any methods impacted by your changes.
+
+### Add an integration test (OPTIONAL)
+
+Adding an integration test is optional, but very much appreciated.
+
+Integration tests are in [`spec/octocatalog-diff/integration`](/spec/octocatalog-diff/integration). Generally, if you're adding a new option, the integration test for that new option will go in its own file.
+
+Please see [integration tests](/doc/dev/integration-tests.md) for more.