diff --git a/doc/dev/run-from-branch.md b/doc/dev/run-from-branch.md new file mode 100644 index 00000000..6717b457 --- /dev/null +++ b/doc/dev/run-from-branch.md @@ -0,0 +1,62 @@ +# Running octocatalog-diff from a branch + +When we are assisting with troubleshooting, or implementing a feature you've requested, we may ask you to run `octocatalog-diff` from a non-master branch to try it out. + +This document is intended for people who may not be familiar with git, GitHub, and/or ruby. If you already know how to do this in another way, feel free! + +## Installation + +1. Determine the branch name. If there's an open Pull Request, you can see the branch name near the top of the page. + + ![Pull Request branch](/doc/images/pull-request-identify-branch.png) + +2. Clone the `octocatalog-diff` repository in your home directory. From the command line: + + ``` + cd $HOME + git clone https://github.com/github/octocatalog-diff.git + ``` + +3. Change into the directory created by your checkout: + + ``` + cd $HOME/octocatalog-diff + ``` + +4. Check out the branch you wish to use, filling in the branch name you determined in the first step: + + ``` + git checkout BRANCH_NAME_FROM_STEP_1 + ``` + +5. Bootstrap the repository to pull in dependencies: + + ``` + ./script/bootstrap + ``` + +6. Optional but recommended - run the test suite: + + ``` + rake + ``` + +## Use + +Now that you have `octocatalog-diff` checked out and bootstrapped, it's time to use it. + +We've created a wrapper script to make this easier for you. + +1. Change directories to the location where you ordinarily run `octocatalog-diff` (for example: in your Puppet repository). + + ``` + cd /etc/puppetlabs/code + ``` + +2. Run the `script/octocatalog-diff-wrapper` script from *this* checkout. For example, if you checked out `octocatalog-diff` to your home directory, you could use: + + ``` + $HOME/octocatalog-diff/script/octocatalog-diff-wrapper + ``` + +:warning: Note: If you are requesting our help, please use the debug option (`-d`) to display debugging information. diff --git a/doc/images/pull-request-identify-branch.png b/doc/images/pull-request-identify-branch.png new file mode 100644 index 00000000..bd28b8a3 Binary files /dev/null and b/doc/images/pull-request-identify-branch.png differ diff --git a/doc/installation.md b/doc/installation.md index 96c31e47..d5fa1036 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -47,3 +47,9 @@ To install from source, you'll need a git client and internet access. Note: If tests fail on your machine with a clean checkout of the master branch, we would definitely appreciate if you would report it. Please [open an issue](https://github.com/github/octocatalog-diff/issues/new) with the output and some information about your system (e.g. OS, ruby version, etc.) to let us know. Once the code is downloaded and bootstrapped, please proceed to [Configuration](/doc/configuration.md). + +## Running from an alternate branch + +We have prepared specific instructions for running `octocatalog-diff` from a non-master branch, for testing changes that may be requested by the developers. + +- [Running octocatalog-diff from a branch](/doc/dev/run-from-branch.md) diff --git a/lib/octocatalog-diff/catalog-diff/cli.rb b/lib/octocatalog-diff/catalog-diff/cli.rb index f5beab7d..745a2921 100644 --- a/lib/octocatalog-diff/catalog-diff/cli.rb +++ b/lib/octocatalog-diff/catalog-diff/cli.rb @@ -166,7 +166,8 @@ def self.setup_logger(logger, options, argv_save) logger.level = Logger::ERROR if options[:quiet] # Some debugging information up front - logger.debug "Running octocatalog-diff #{VERSION} with ruby #{RUBY_VERSION}" + version_display = ENV['OCTOCATALOG_DIFF_CUSTOM_VERSION'] || VERSION + logger.debug "Running octocatalog-diff #{version_display} with ruby #{RUBY_VERSION}" logger.debug "Command line arguments: #{argv_save.inspect}" logger.debug "Running on host #{Socket.gethostname} (#{RUBY_PLATFORM})" end diff --git a/script/octocatalog-diff-wrapper b/script/octocatalog-diff-wrapper new file mode 100755 index 00000000..8f3104ba --- /dev/null +++ b/script/octocatalog-diff-wrapper @@ -0,0 +1,17 @@ +#!/bin/bash + +# This script exists to make it easier to test alternate branches of octocatalog-diff. +# It is intended as a one-for-one replacement of `octocatalog-diff` as installed by the gem. + +CURRENT_PWD="$(pwd)" +CHECKOUT_BASE="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && cd .. && pwd )" + +if [ -z "$OCTOCATALOG_DIFF_CONFIG_FILE" ]; then + if [ -f "${CURRENT_PWD}/.octocatalog-diff.cfg.rb" ]; then + export OCTOCATALOG_DIFF_CONFIG_FILE="${CURRENT_PWD}/.octocatalog-diff.cfg.rb" + fi +fi + +cd "$CHECKOUT_BASE" +export OCTOCATALOG_DIFF_CUSTOM_VERSION="@$(git rev-parse HEAD)" +bundle exec bin/octocatalog-diff --basedir "$CURRENT_PWD" $* diff --git a/spec/octocatalog-diff/tests/catalog-diff/cli_spec.rb b/spec/octocatalog-diff/tests/catalog-diff/cli_spec.rb index 185b0b94..be1df526 100644 --- a/spec/octocatalog-diff/tests/catalog-diff/cli_spec.rb +++ b/spec/octocatalog-diff/tests/catalog-diff/cli_spec.rb @@ -115,6 +115,37 @@ end end + describe '#setup_logger' do + context 'with custom version specified in environment' do + before(:each) do + ENV['OCTOCATALOG_DIFF_CUSTOM_VERSION'] = '@d05c30152c897219367d586414ccb1f651ab7221' + end + + after(:each) do + ENV.delete 'OCTOCATALOG_DIFF_CUSTOM_VERSION' + end + + it 'should log custom version' do + logger, logger_str = OctocatalogDiff::Spec.setup_logger + described_class.setup_logger(logger, { debug: true }, nil) + expect(logger_str.string).to match(/Running octocatalog-diff @d05c30152c897219367d586414ccb1f651ab7221 with ruby/) + end + end + + context 'with default version' do + before(:each) do + ENV.delete 'OCTOCATALOG_DIFF_CUSTOM_VERSION' + end + + it 'should log current version' do + logger, logger_str = OctocatalogDiff::Spec.setup_logger + described_class.setup_logger(logger, { debug: true }, nil) + version = described_class::VERSION + expect(logger_str.string).to match(/Running octocatalog-diff #{version} with ruby/) + end + end + end + describe '#setup_fact_overrides' do it 'should make no adjustments when there are no fact overrides' do options = {}