Initial release

Author: Kevin Paulisse

.github/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Hi there! We're thrilled that you'd like to contribute to :octocat:alog-diff. Your help is essential for keeping it great.
+
+Please note that this project adheres to the [Open Code of Conduct](http://todogroup.org/opencodeofconduct/#GitHub%20Octocatalog-Diff/[email protected]). By participating in this project you agree to abide by its terms.
+
+We strongly recommend that you check out the [roadmap](/doc/roadmap.md) before getting started. If you have questions, or you'd like to check with us before embarking on a major development effort, please [open an issue](https://github.com/github/octocatalog-diff/issues/new).
+
+## How to contribute
+
+This project uses the [GitHub Flow](https://guides.github.com/introduction/flow/). That means that the `master` branch is stable and new development is done in feature branches. Feature branches are merged into the `master` branch via a Pull Request.
+
+0. Fork and clone the repository
+0. Configure and install the dependencies: `script/bootstrap`
+0. Make sure the tests pass on your machine: `rake`
+0. Create a new branch: `git checkout -b my-branch-name`
+0. Make your change, add tests, and make sure the tests still pass
+0. Push to your fork and submit a pull request
+0. Pat yourself on the back and wait for your pull request to be reviewed and merged
+
+We will handle updating the version, tagging the release, and releasing the gem. Please don't bump the version or otherwise attempt to take on these administrative internal tasks as part of your pull request.
+
+Here are a few things you can do that will increase the likelihood of your pull request being accepted:
+
+- Make sure your contribution is consistent with our [roadmap](roadmap.md).
+
+- Follow the [style guide](https://github.com/bbatsov/ruby-style-guide).
+
+  - We support Ruby 2.0 and higher. This means, for example, that you can use the 2.0 hash syntax (e.g. `options = { font_size: 10, font_family: 'Arial' }`, but **not** the 2.1 keyword arguments for methods (e.g., `def foo(bar: 'baz')`).
+
+  - We use single quotes (`'`) rather than double quotes (`"`) for strings with no interpolation.
+
+  - We use [rubocop](http://batsov.com/rubocop/) to enforce style, because we strive for efficient code reviews. You can view our [.rubocop.yml rules file](/.rubocop.yml) or use `script/fmt` in your checkout to run Rubocop with our rule set. If you use our bootstrap script when cloning your repo, you will have installed Rubocop as a pre-commit hook in the repository.
+
+- Write unit tests. Each changed or added method should be covered by [unit tests](/spec/octocatalog-diff/tests). You can create a [coverage report](/doc/dev/coverage.md) via our rake task if you wish. We'd like to maintain 100% on unit test coverage (`rake coverage:spec`). You can use simplecov comments (`# :nocov:`) to wrap portions of code that it is impractical or not worthwhile to test.
+
+- Write an integration test. For any new features, e.g. when you have added a new command line flag, please consider adding an [integration test](/spec/octocatalog-diff/integration). You can check integration test coverage with `rake coverage:integration`. We do not demand 100% coverage here, as it is impractical to test all possible error conditions. However, it would be great if the important parts of your code are exercised in the integration tests.
+
+- Write or update documentation. If you have added a feature or changed an existing one, please make appropriate changes to the docs. Please note that the [options reference](/doc/optionsref.md) is automatically generated, so you do not need to update that file. (Or, you can run `rake doc:build` to rebuild it.)
+
+- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
+
+- We target `octocatalog-diff` to support Puppet 3.8.7 and 4.5 (and subsequent releases). There were some changes to the catalog format between these versions. We have abstracted these differences with methods such as `resources` in the [catalog object](/lib/octocatalog-diff/catalog.rb), but if you are directly interacting with the JSON of the catalog, be careful of this. Our CI job will test with both Puppet 3 and Puppet 4, so writing complete tests are a good way of ensuring that your code is compatible.
+
+- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+
+## License note
+
+We can only accept contributions that are compatible with the MIT license.
+
+It's OK to depend on gems licensed under either Apache 2.0 or MIT, but we cannot add dependencies on any gems that are licensed under GPL.
+
+Any contributions you make must be under the MIT license.
+
+## Resources
+
+- [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/)
+- [Using Pull Requests](https://help.github.com/articles/using-pull-requests/)
+- [GitHub Help](https://help.github.com)

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!--
+Hi there! If you are reporting a bug or a problem, please use this template so that we can collect the information that we need in order to help. If you are opening an issue for a reason other than reporting a problem, e.g. to make a feature request or start a discussion of new functionality, then you do not need to follow the template.
+
+Please remember that all activity in this project, including issues, needs to comply with the Open Code of Conduct, found here: http://todogroup.org/opencodeofconduct/
+-->
+
+> Description of problem
+
+- What did you do?
+- What happened?
+- What did you expect to happen?
+- How can someone reproduce the problem?
+
+> Command used and debugging output
+
+<!--
+If you are reporting a problem or bug, please replace this text with the command you are using (including all arguments) and the output from that command. Please add the `--debug` command line flag to enable debugging output. You may redact any information you consider sensitive.
+-->
+
+> Platform and version information
+
+- Your OS: <!-- Mac OS? Linux? Which version and distribution? -->
+- Your Ruby version: <!-- type `ruby --version` at the command prompt -->
+- Your version of Puppet: <!-- version number, and whether it's open source or Puppet Enterprise -->
+- Your version of octocatalog-diff: <!-- type `octocatalog-diff --version` -->
+
+> Do the tests pass from a clean checkout?
+
+<!-- Please refer to https://github.com/github/octocatalog-diff/blob/master/doc/troubleshooting.md for instructions to check out the master branch and run the tests. If you encounter any errors from the tests, please post them here. -->
+
+> Anything else to add that you think will be helpful?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+<!--
+Hi there! We are delighted that you have chosen to contribute to octocatalog-diff.
+
+If you have not already done so, please read our Contributing document, found here: https://github.com/github/octocatalog-diff/blob/master/.github/CONTRIBUTING.md
+
+Please remember that all activity in this project, including pull requests, needs to comply with the Open Code of Conduct, found here: http://todogroup.org/opencodeofconduct/
+
+Any contributions to this project must be made under the MIT license.
+
+You do NOT need to bump the version number or regenerate the "Command line options reference" page. We will do this for you at or after the time we merge your contribution.
+-->
+
+## Overview
+
+This pull request [introduces/changes/removes] [functionality/feature].
+
+(Please write a summary of your pull request here. This paragraph should go into detail about what is changing, the motivation behind this change, and the approach you took.)
+
+## Checklist
+
+- [ ] Make sure that all of the tests pass, and fix any that don't. Just run `rake` in your checkout directory, or review the CI job triggered whenever you push to a pull request.
+- [ ] Make sure that there is 100% [test coverage](https://github.com/github/octocatalog-diff/blob/master/doc/dev/coverage.md) by running `rake coverage:spec` or ignoring untestable sections of code with `# :nocov` comments. If you need help getting to 100% coverage please ask; however, don't just submit code with no tests.
+- [ ] If you have added a new command line option, we would greatly appreciate a corresponding [integration test](https://github.com/github/octocatalog-diff/blob/master/doc/dev/integration-tests.md) that exercises it from start to finish. This is optional but recommended.
+- [ ] If you have added any new gem dependencies, make sure those gems are licensed under the MIT or Apache 2.0 license. We cannot add any dependencies on gems licensed under GPL.
+- [ ] If you have added any new gem dependencies, make sure you've checked in a copy of the `.gem` file into the [vendor/cache](https://github.com/github/octocatalog-diff/tree/master/vendor/cache) directory.
+
+/cc [related issues] [teams and individuals, making sure to mention why you're CC-ing them]

.gitignore

@@ -0,0 +1,78 @@
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Specifics for octocatalog-diff
+bin/bundler
+bin/facter
+bin/hiera
+bin/htmldiff
+bin/httparty
+bin/ldiff
+bin/parallel_cucumber
+bin/parallel_rspec
+bin/parallel_spinach
+bin/parallel_test
+bin/puppet
+bin/rake
+bin/rspec
+bin/rubocop
+bin/ruby-parse
+bin/ruby-rewrite
+bin/safe_yaml
+
+# Ignore config created during testing
+.puppet_version
+.parallel_runtime_rspec.log
+.parallel_runtime_integration.log
+.parallel_runtime_tests.log
+.rspec_parallel
+
+# Packaged gem
+/pkg/
+Gemfile.lock

.rubocop.yml

@@ -0,0 +1,51 @@
+AllCops:
+  TargetRubyVersion: 2.0
+  DisplayCopNames: true
+
+LineLength:
+  Max: 130
+  Severity: warning
+
+Style/OneLineConditional:
+  Enabled: true
+
+Style/StringLiterals:
+  # Being consistent with Puppet
+  EnforcedStyle: single_quotes
+
+# Since we're using Ruby >= 2.0 we can use the new hash syntax
+Style/HashSyntax:
+  Enabled: true
+
+# We are setting absurdly high limits but should work to tighten these up.
+Metrics/AbcSize:
+  Max: 100
+  Severity: warning
+
+Metrics/ClassLength:
+  Max: 500
+  Severity: warning
+
+Metrics/CyclomaticComplexity:
+  Max: 50
+  Severity: warning
+
+Metrics/MethodLength:
+  Max: 100
+  Severity: warning
+
+Metrics/PerceivedComplexity:
+  Max: 50
+  Severity: warning
+
+# Indentation
+CaseIndentation:
+  IndentWhenRelativeTo: end
+  IndentOneStep: false
+
+Lint/EndAlignment:
+  AlignWith: variable
+
+# To let us use a '-' in the gem name
+Style/FileName:
+  Enabled: false

.travis.yml

@@ -0,0 +1,18 @@
+# octocatalog-diff
+
+language: ruby
+install: true
+script: "script/cibuild"
+
+matrix:
+  include:
+    # Build with latest ruby
+    - rvm: 2.3.1
+      env: RUBOCOP_TEST="true" RSPEC_TEST="true"
+    # Build with older ruby versions
+    - rvm: 2.2
+      env: RUBOCOP_TEST="false" RSPEC_TEST="true"
+    - rvm: 2.1
+      env: RUBOCOP_TEST="false" RSPEC_TEST="true"
+    - rvm: 2.0
+      env: RUBOCOP_TEST="false" RSPEC_TEST="true"

.version

@@ -0,0 +1 @@
+0.5.0

Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,82 @@
+# octocatalog-diff
+
+#### Compile Puppet catalogs from 2 branches, versions, etc., and compare them <img src="/doc/images/octocatolog-diff-logo.png" align="right" height=126 width=240>
+
+`octocatalog-diff` is a tool that enables developers to be more efficient when testing changes to Puppet manifests. It is most commonly used to display differences in Puppet catalogs between stable and development branches. It does not require a working Puppet master (or puppetserver), so it is often run by developers on their workstations and in Continuous Integration environments.
+
+At GitHub, we manage thousands of nodes with a Puppet code base containing 500,000+ lines of code from over 200 contributors. We run `octocatalog-diff` thousands of times per day as part of Continuous Integration testing, and developers run it on their workstations as they are working with the code.
+
+`octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
+
+It is under active development at this time. We suspect that with the initial release, some people who try it out could be using configurations of Puppet that we haven't experienced within our environment. We are eager to identify and fix as many of these as we can to expand the compatibility of this tool as much as possible.
+
+## How?
+
+Traditional Puppet development generally takes one of two forms. Frequently, developers will test changes by running a Puppet agent (perhaps in `--noop` mode) to see if the desired change has resulted on an actual system. Others will use formal testing methodologies, such as `rspec-puppet` or the beaker framework to validate Puppet code.
+
+`octocatalog-diff` uses a different pattern. In its most common invocation, it compiles Puppet catalogs for both the stable branch (e.g. master) and the development branch, and then compares them. It filters out attributes or resources that have no effect on ultimate state of the target system (e.g. tags) and displays the remaining differences. Using this strategy, one can get feedback on changes without deploying Puppet code to a server and conducting a full Puppet run, and this tool works even if test coverage is incomplete.
+
+There are some [limitations](doc/limitations.md) to a catalog-based approach, meaning it will never completely replace unit, integration, or deployment testing. However, it does provide substantial time savings in both the development and testing cycle. In this repository, we provide example scripts for using `octocatalog-diff` in development and CI environments.
+
+`octocatalog-diff` is currently able to get catalogs by the following methods:
+- Compile catalog via the command line with a Puppet agent on your machine (as GitHub uses the tool internally)
+- Obtain catalog over the network from PuppetDB
+- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x and 4.x supported)
+- Read catalog from a JSON file
+
+## Example
+
+Here is simulated output from running `octocatalog-diff` to compare the Puppet catalog changes between the master branch and the Puppet code in the current working directory:
+
+<img src="doc/images/screenshot1.png" alt="[octocatalog-diff screenshot]">
+
+The example above reflects the changes in the Puppet catalog from switching an underlying device for a mounted file system.
+
+## Documentation
+
+### Installation and use in a development environment
+
+- [Installation](/doc/installation.md)
+- [Configuration](/doc/configuration.md)
+- [Basic command line usage](/doc/basic.md)
+- [Advanced command line usage](/doc/advanced.md)
+- [Troubleshooting](/doc/troubleshooting.md)
+
+### Installation and use for CI
+
+- [Setting up octocatalog-diff in CI](/doc/advanced-ci.md)
+
+### Technical details
+
+- [Requirements](/doc/requirements.md)
+- [Limitations](/doc/limitations.md)
+- [List of all command line options](/doc/optionsref.md)
+
+### Project
+
+- [Roadmap](/doc/roadmap.md)
+- [Similar tools](/doc/similar.md)
+- [Contributing](/.github/CONTRIBUTING.md)
+- [Developer documentation](/doc/dev)
+
+## What's in a name?
+
+During its original development at GitHub, this tool was simply called `catalog-diff`. However, there is already a [Puppet module with that name](https://forge.puppet.com/zack/catalog_diff) and we didn't want to create any confusion (in fact, a case could be made to use both approaches). So, we named the tool `octocatalog-diff` because who doesn't like the [octocat](https://octodex.github.com/)? Then one day in chat, someone referred to the tool as ":octocat:alog-diff", and that moniker caught on for electronic communication.
+
+## Contributing
+
+Please see our [contributing document](/.github/CONTRIBUTING.md) if you would like to participate!
+
+## Getting help
+
+If you have a problem or suggestion, please [open an issue](https://github.com/github/octocatalog-diff/issues/new) in this repository, and we will do our best to help. Please note that this project adheres to the [Open Code of Conduct](http://todogroup.org/opencodeofconduct/#GitHub%20Octocatalog-Diff/[email protected]).
+
+## License
+
+`octocatalog-diff` is licensed under the [MIT license](LICENSE).
+
+It requires 3rd party ruby gems found [here](/vendor/cache). It also includes portions of other open source projects [here](/lib/octocatalog-diff/external/pson), [here](/spec/octocatalog-diff/fixtures/repos/default/modules/stdlib), [here](/spec/octocatalog-diff/support/httparty) and [here](/spec/octocatalog-diff/tests/external/pson). All 3rd party code and required gems are licensed either as MIT or Apache 2.0.
+
+## Authors
+
+`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by the Site Reliability Engineering team at GitHub.