puppet 2.7.1 → 2.7.3

data/CHANGELOG

@@ -1,3 +1,183 @@
+2.7.3
+===
+7113448 (#4762) Ensure that clients on the moon can successfully connect.
+c8835ad Add document outlining preferred contribution methods
+b85f57c Add document outlining preferred contribution methods
+ea0f2bf Revert "Merge branch 'vcsrepo'"
+a5716e4 Revert "Merge branch 'vcsrepo'"
+94f0b93 (#8704) Give better errors for invalid fileserver.conf
+38801dd (Maint.) Disable cleaning of storeconfigs.
+023d959 (#8690) Accept 'global' options in Puppet Faces
+bff817c (Maint.) Fix spec failures related to leaking state.
+ccd622a (#1886) Clean up `node clean` for merge.
+c315da0 Fix #1886 - Add node cleanup capability
+7e6fc0d Deprecate RestAuthConfig#allowed? in favor of #check_authorization
+6401dfe Fix #6026 - security file should support inline comments
+0c385f1 Fix #5010 - Allow leading whitespace in auth.conf
+8da0486 Fix #5777 - rule interpolation broke auth.conf CIDR rules
+1d4acb5 maint: Suggest where to start troubleshooting SSL error message
+fb2ffd6 (#8596) Detect resource alias conflicts when titles do not match
+778127d maint: Fix cert app to print help and exit if no subcommand
+0366b18 (#7293) Set default format for SSL-related faces.
+cc2c3ed (Maint.) Unquoting HEREDOCs.
+89c021c (#8418) Fix inspect app to have the correct run_mode
+3165364 maint: Adding logging to include environment when source fails
+f484851 maint: Add debug logging when the master receives a report
+10e05ad (#7266) Move Certificate option validation into face.
+d522b0b maint: Fix Face testing bug 1.9.2 revealed.
+ae36003 (#7290) Update indirected Faces to avoid unknown options.
+88e9cd2 maint: don't print inside action implementations.
+82e5fa9 (#8561, #7290) Implement the option contract fully.
+77441be (#8561) Unify validation and modification of action arguments.
+69b4e70 (#7290) Fail on unknown options.
+6bec2df (#8561) Use canonical names for options to actions.
+532c4f3 (#7184) Load the core of obsolete versions of Faces.
+2cd3bc4 (#7184) Find actions bound to other versions of Faces.
+1e0655e (#7184) Centralize "find action for face" into Puppet::Face
+0396611 maint: better error reporting when test fails
+e639868 Confine password disclosure acceptance test to hosts with required libraries
+395c174 (#7123) Make `find` the default action...
+fd6a653 (#7123) Support runtime setting of 'default' on actions.
+b75b1c1 (#6787) Add `default_to` for options.
+8820a78 Replace calls to Array#count with #length
+bdd6a17 Fix order-dependent test failure in certificate_status/file spec
+c830ab0 (#6789) Port SSL::CertificateAuthority::Interface to a Face
+cc311ad maint: SSL::Inventory.serial should report missing names.
+72abe6c (#7204) Consolidate Semantic Versioning code.
+d02000b (#8401) Document that --detailed-exitcodes is a bitmask
+a109c90 (maint) Cleanup and strengthen acceptance tests
+c4848d2 maint: Fix documentation link for fileserver configuration
+b268fb3 (#7144) Update Settings#writesub to convert mode to Fixnum
+b82f29c (#7699) Help command should only list options once
+4a2f22c (maint) Fix platform dection for RHEL
+45b3908 (#4142) Fix module check not to fail when empty metadata.json
+1feccc3 Revert "Merge branch 'ticket/2.7.x/7699_fix_help_listing_options_twice' into 2.7.x"
+ae3ef42 (#7699) - Help should only show options once
+5826f73 (#8032) Add containment to create_resources
+98cd89b (#8147) Update test for default reporturl
+f6882d6 (#8147) Change default reporturl to match newer Dashboard versions
+111a4b5 (#6857) Password disclosure when changing a user's password
+Fix cross branch confusion on 2.7.2rc2
+8ec0804 (#8301) Red Hat spec file for 2.7.2rc1 won't work
+2263be6 (#5108) Update service type docs for new hasstatus default
+902c414 Update configurer_spec.rb to work with Ruby 1.8.5
+7ad1b04 Clean up indentation, whitespace, and commented out code
+014d952 Remove order dependency from functions integration spec
+243aaa9 (#7956) Porting cron tests
+3e3fc69 (#7956) Port resource acceptance tests
+534ccfe (#8048) Gem install puppet no longer fails if rdoc enabled.
+bbde5b5 Readying for release of 2.6.9
+5160822 Clean up indentation, whitespace, and commented out code
+92a8f4a Remove order dependency from functions integration spec
+31554c0 (#6854) Update Red Hat spec file
+cba645c Bumping release in lib/puppet.rb and updating CHANGELOG.
+43027de Bumping RPM spec file to 2.6.9rc1.
+99330fa (#7224) Reword 'hostname was not match' error message
+1d867b0 (#7224) Add a helper to Puppet::SSL::Certificate to retrieve alternate names
+db1a392 (#7506) Organize READMEs; specify supported Ruby versions in README.md
+de06469 (#5641) Help text: document that puppet doc takes modulepath, manifestdir, and environment options
+381fa40 (#6418) Make test 64118 more portable
+98ba407 (#7127) Stop puppet if a prerun command fails
+6996e0b Do not needlessly create multiple reports when creating a transaction
+caca469 (#4416) Ensure types are providified after reloading
+413b136 (#4416) Always remove old provider before recreating it
+d866ce1 Cleanup indentation, comment, and unused code
+d1c965a Make temporary auth.conf in acceptance test readable by Puppet
+4af9784 (#7117) Use a different auth.conf instead of overwriting the default
+ecde134 (#3360) Delete SSL directory in acceptance test before running
+b502423 Update acceptance tests to use with_master_running_on
+053e613 Remove pending copy of an active acceptance test
+98f58ce (#2128) Add WARNING for node_name_{fact,value} descriptions
+1cd848c (#2128) Whitespace only reflow commit
+d9b5c1a (#2128) In-line docs for node_name_{fact,value}
+3f0dbb5 (#650) Allow symlinks for configuration directories
+c260cf1 Fix acceptance tests not managing their masters
+1c70f0c (#2128) Add support for setting node name based on a fact
+c629958 (#2128) Get facts before retrieving catalog
+cd4fe14 (#2128) Add the ability to specify a node name
+8ebec1e (#7193) Fix path issues with acceptance tests that call old shell tests
+16b2311 (#6885) puppet agent fingerprint requires --verbose to return a value.
+77a5987 maint: Confine augeas specs to require the augeas feature
+8eb0e16 (#2728) Add diff output for changes made by Augeas provider
+a00fd25 maint: Refactor specs in preparation for making node name more flexible
+2f8bc26 maint: Fix order dependent test failure
+c02126d (#5966) Add support for hostname regular expressions in auth.conf
+75e2764 (#5318) Always notice changes to manifests when compiling.
+bc71266 maint: Fix order dependent spec failure for face indirection
+6547835 (#7690) Don't blow up when listing terminuses available for faces
+0bcbca5 maint: Dedup the loadpath so we don't have to walk it multiple times
+4a5e99d (#7681) Add an acceptance test for resource refs with array variables
+996dc07 Maint: Fix ellipses for short descriptions
+53af6f3 (#7563) DRY: Remove indirector boilerplate from individual faces
+74aff59 (#7564) Finish templates
+3026333 (#7561) Complete help text for all faces and actions
+13e473e Maint: Add ellipsis to generated short_descriptions.
+89d447b (#6962) Add "arguments" method to help API
+646919e (4123) Fix test for 4123/4 on old egrep in cent4
+b101804 add puppet master polling step for ticket 7117
+9145569 maint: Remove reliance on system clock from schedule spec tests
+107b38a maint: Fix pacman provider to work with Ruby 1.9
+8eea3f5 Added the vcsrepo type and providers to the core
+8f0cecf Added the vcsrepo type and providers to the core
+4645c99 add puppet master polling step for ticket 7117
+17e7223 (#7507) Add exclude filter for ruby 1.9 spec failures
+181098b (#7502) Fixed parser spec for ruby 1.8.5
+9c3bedd (#7507) Add more 1.9 filters
+f037662 (#6395) Add extpuppet help, eval, and interfaces
+4d4d587 Adding a sleep state post starting master
+c81f5c6 Adding a sleep state post starting master
+d1cc24f maint: fix spec_helper inclusions again.
+3ac7aed (#7523) Refactor the grammar to reduce duplication
+d22b130 (#7114) Fix specs for ssh authorized key parsed provider
+551cb3e (#7114) Target returns correct value
+15c6fc7 (#7114) Add integration tests for authorized_key
+a5ac82a (#7114) Improve unit tests for ssh_authorized_key
+1c7f0c3 (#7114) Improve value validation for authorized_key
+0b8ebac (#7300) Fix instances method of mount provider
+1dc662a (#1853) Pacman package provider
+6bb2a85 (#1853) Pacman package provider
+c8775f9 (#7259) Remove ActiveRecord requirement from indirector face spec
+1ad8158 (#7259) Do not try to load all Terminus classes when configuring the Indirector
+8b76be3 (#3836) External nodes should only capture stdout
+d63fc34 Revert "(#7220) Add the ability to "inherit" options."
+c21539f maint: sync 'authconfig' to 'rest_authconfig' setting
+81d566f Fixed #7481 - Added MIT license to Thomas Bellman's function code
+1695dac (#7264) Docs: Clarify that subscribe/notify imply require/before
+8f907f2 adding test for ticket 7139
+90eb937 (#7139) Accept '/' as a valid path in filesets
+1f3b8e7 (#7300) Add specs for the mount provider
+1b2a7d9 case seems needless here as there is only two opts, also the rest of the file seems to use if so this should make things more consistant
+729336e (#6845) Mount writes incorrect vfstab entries
+16cf1ac (#6442) Be able to start agents --listen without namespaceauth.conf
+e059539 Update CHANGELOG for 2.6.8
+ac0581f (#7101) Fix template error messages in Ruby 1.8.5
+9d2500e (#7101) Fix template error messages in Ruby 1.8.5
+0352402 (#3420) Nagios "name" attribute does not output correctly
+f656818 (#4487) When setting environment on a host, ensure it is a string.
+89e9a21 add test for ticket 7101
+74498af add test for ticket 7101
+2cce326 add test for ticket 7101
+c1edcb2 add test for ticket 7101
+9329a1f (#7220) Add the ability to "inherit" options.
+c306db2 (#6487) Add some testing for OS X version support in DirectoryService provider
+0008b63 (#6487) Directoryservice provider will fail in future OS releases
+f21162b (#6368) Make the File type autorequire its nearest ancestor directory
+c3a76a9 (#7021) Fix order dependent spec failures
+7bd6a2f maint: Remove unused code
+34f9f41 Maint: Fix a #4655 introduced log inconsistency
+6981ee5 Maint: Fix a #4655 introduced log inconsistency
+cb43cfc Moving tests from Puppet-acceptance repo
+ac428b9 Move tests from Puppet-acceptance repo
+db26326 Move tests from puppet-acceptance repo
+6b18f8f Move acceptance tests from puppet-acceptance repo
+9a5bf6e Fixed #7166 - Replaced deprecated stomp "send" method with "publish"
+a18ac78 maint: Fix PSON order dependency in test
+656eff8 (#4655) Allow stage to be set using a default class parameter
+b3ab0d9 (#4655) Allow stage to be set using a default class parameter
+7d3c303 Fixed #7166 - Replaced deprecated stomp "send" method with "publish"
+7f658e6 vim: Initial ftplugin and indent support
+ccbe9f3 Fixed #6681 - Remove --force-yes option from aptitude is used
+
 2.7.1
 ===
 a49d5b8 (#8048) Gem install puppet no longer fails if rdoc enabled.
@@ -734,8 +914,52 @@ d532e6d Fixing #3185 Rakefile is loading puppet.rb twice
 5aa596c Fix #3150 - require function doesn't like ::class syntax
 3457b87 Added time module to tagmail report
 
-2.6.8rc1
+2.6.9
 ====
+db1a392 (#7506) Organize READMEs; specify supported Ruby versions in README.md
+381fa40 (#6418) Make test 64118 more portable
+98ba407 (#7127) Stop puppet if a prerun command fails
+6996e0b Do not needlessly create multiple reports when creating a transaction
+caca469 (#4416) Ensure types are providified after reloading
+413b136 (#4416) Always remove old provider before recreating it
+d866ce1 Cleanup indentation, comment, and unused code
+98f58ce (#2128) Add WARNING for node_name_{fact,value} descriptions
+1cd848c (#2128) Whitespace only reflow commit
+d9b5c1a (#2128) In-line docs for node_name_{fact,value}
+3f0dbb5 (#650) Allow symlinks for configuration directories
+c260cf1 Fix acceptance tests not managing their masters
+1c70f0c (#2128) Add support for setting node name based on a fact
+c629958 (#2128) Get facts before retrieving catalog
+cd4fe14 (#2128) Add the ability to specify a node name
+8ebec1e (#7193) Fix path issues with acceptance tests that call old shell tests
+16b2311 (#6885) puppet agent fingerprint requires --verbose to return a value.
+a00fd25 maint: Refactor specs in preparation for making node name more flexible
+75e2764 (#5318) Always notice changes to manifests when compiling.
+4a5e99d (#7681) Add an acceptance test for resource refs with array variables
+646919e (4123) Fix test for 4123/4 on old egrep in cent4
+8b76be3 (#3836) External nodes should only capture stdout
+8f907f2 adding test for ticket 7139
+90eb937 (#7139) Accept '/' as a valid path in filesets
+1b2a7d9 case seems needless here as there is only two opts, also the rest of the file seems to use if so this should make thin
+729336e (#6845) Mount writes incorrect vfstab entries
+16cf1ac (#6442) Be able to start agents --listen without namespaceauth.conf
+0352402 (#3420) Nagios "name" attribute does not output correctly
+f656818 (#4487) When setting environment on a host, ensure it is a string.
+2cce326 add test for ticket 7101
+c306db2 (#6487) Add some testing for OS X version support in DirectoryService provider
+0008b63 (#6487) Directoryservice provider will fail in future OS releases
+34f9f41 Maint: Fix a #4655 introduced log inconsistency
+6b18f8f Move acceptance tests from puppet-acceptance repo
+9a5bf6e Fixed #7166 - Replaced deprecated stomp "send" method with "publish"
+656eff8 (#4655) Allow stage to be set using a default class parameter
+7f658e6 vim: Initial ftplugin and indent support
+ccbe9f3 Fixed #6681 - Remove --force-yes option from aptitude is used
+
+2.6.8
+=====
+c1edcb2 add test for ticket 7101
+db26326 Move tests from puppet-acceptance repo
+bee1ef7 Updated CHANGELOG for 2.6.8rc1
 8b7444d (#2331) Remove darwinports pkg provider, replace with rewritten macports provider
 65c4e14 Fixed #7082 - Added system support for groups
 b7f4ff7 (#7018) Give more context on the service type's assumptions. Wording tweaks.

data/CONTRIBUTING.md

@@ -0,0 +1,299 @@
+Checklist (and a short version for the impatient)
+=================================================
+
+  * Commits:
+
+    - Make commits of logical units.
+
+    - Check for unnecessary whitespace with "git diff --check" before
+      committing.
+
+    - Commit using Unix line endings (check the settings around "crlf" in
+      git-config(1)).
+
+    - Do not check in commented out code or unneeded files.
+
+    - The first line of the commit message should be a short
+      description (50 characters is the soft limit, excluding ticket
+      number(s)), and should skip the full stop.
+
+    - If there is an associated Redmine ticket then the first line
+      should include the ticket number in the form "(#XXXX) Rest of
+      message".
+
+    - The body should provide a meaningful commit message, which:
+
+      - uses the imperative, present tense: "change", not "changed" or
+        "changes".
+
+      - includes motivation for the change, and contrasts its
+        implementation with the previous behavior.
+
+    - Make sure that you have tests for the bug you are fixing, or
+      feature you are adding.
+
+    - Make sure the test suite passes after your commit (rake spec unit).
+
+  * Submission:
+
+    * Pre-requisites:
+
+      - Make sure you have a [Redmine account](http://projects.puppetlabs.com)
+
+      - Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
+
+    * Preferred method:
+
+      - Fork the repository on GitHub.
+
+      - Push your changes to a topic branch in your fork of the
+        repository.
+
+      - Submit a pull request to the repository in the puppetlabs
+        organization.
+
+    * Alternate methods:
+
+      - Mail patches to puppet-dev mailing list using `rake mail_patches`,
+        or `git-format-patch(1)` & `git-send-email(1)`.
+
+      - Attach patches to Redmine ticket.
+
+The long version
+================
+
+  0.  Decide what to base your work on.
+
+      In general, you should always base your work on the oldest
+      branch that your change is relevant to.
+
+      - A bug fix should be based on the current stable series. If the
+        bug is not present in the current stable release, then base it on
+        `master`.
+
+      - A new feature should be based on `master`.
+
+      - Security fixes should be based on the current maintenance series
+        (that is, the previous stable series).  If the security issue
+        was not present in the maintenance series, then it should be
+        based on the current stable series if it was introduced there,
+        or on `master` if it is not yet present in a stable release.
+
+      The current stable series is 2.7.x, and the current maintenance
+      series is 2.6.x.
+
+  1.  Make separate commits for logically separate changes.
+
+      Please break your commits down into logically consistent units
+      which include new or changed tests relevent to the rest of the
+      change.  The goal of doing this is to make the diff easier to
+      read for whoever is reviewing your code.  In general, the easier
+      your diff is to read, the more likely someone will be happy to
+      review it and get it into the code base.
+
+      If you're going to refactor a piece of code, please do so as a
+      separate commit from your feature or bug fix changes.
+
+      We also really appreciate changes that include tests to make
+      sure the bug isn't re-introduced, and that the feature isn't
+      accidentally broken.
+
+      Describe the technical detail of the change(s).  If your
+      description starts to get too long, that's a good sign that you
+      probably need to split up your commit into more finely grained
+      pieces.
+
+      Commits which plainly describe the the things which help
+      reviewers check the patch and future developers understand the
+      code are much more likely to be merged in with a minimum of
+      bike-shedding or requested changes.  Ideally, the commit message
+      would include information, and be in a form suitable for
+      inclusion in the release notes for the version of Puppet that
+      includes them.
+
+      Please also check that you are not introducing any trailing
+      whitespaces or other "whitespace errors".  You can do this by
+      running "git diff --check" on your changes before you commit.
+
+  2.  Sign the Contributor License Agreement
+
+      Before we can accept your changes, we do need a signed Puppet
+      Labs Contributor License Agreement (CLA).
+
+      You can access the CLA via the
+      [Contributor License Agreement link](https://projects.puppetlabs.com/contributor_licenses/sign)
+      in the top menu bar of our Redmine instance.  Once you've signed
+      the CLA, a badge will show up next to your name on the
+      [Puppet Project Overview Page](http://projects.puppetlabs.com/projects/puppet?jump=welcome),
+      and your name will be listed under "Contributor License Signers"
+      section.
+
+      If you have any questions about the CLA, please feel free to
+      contact Puppet Labs via email at cla-submissions@puppetlabs.com.
+
+  3.  Sending your patches
+
+      We accept multiple ways of submitting your changes for
+      inclusion.  They are listed below in order of preference.
+
+      Please keep in mind that any method that involves sending email
+      to the mailing list directly requires you to be subscribed to
+      the mailing list, and that your first post to the list will be
+      held in a moderation queue.
+
+      * GitHub Pull Requests
+
+        To submit your changes via a GitHub pull request, we _highly_
+        recommend that you have them on a topic branch, instead of
+        directly on "master" or one of the release, or RC branches.
+        It makes things much easier to keep track of, especially if
+        you decide to work on another thing before your first change
+        is merged in.
+
+        GitHub has some pretty good
+        [general documentation](http://help.github.com/) on using
+        their site.  They also have documentation on
+        [creating pull requests](http://help.github.com/send-pull-requests/).
+
+        In general, after pushing your topic branch up to your
+        repository on GitHub, you'll switch to the branch in the
+        GitHub UI and click "Pull Request" towards the top of the page
+        in order to open a pull request.
+
+        You'll want to make sure that you have the appropriate
+        destination branch in the repository under the puppetlabs
+        organization.  This should be the same branch that you based
+        your changes off of.
+
+      * Other pull requests
+
+        If you already have a publicly accessible version of the
+        repository hosted elsewhere, and don't wish to or cannot use
+        GitHub, you can submit your change by requesting that we pull
+        the changes from your repository by sending an email to the
+        puppet-dev Google Groups mailing list.
+
+        `git-request-pull(1)` provides a handy way to generate the text
+        for the email requesting that we pull your changes (and does
+        some helpful sanity checks in the process).
+
+      * Mailing patches to the mailing list
+
+        If neither of the previous methods works for you, then you can
+        also mail the patches inline to the puppet-dev Google Group
+        using either `rake mail_patches`, or by using
+        `git-format-patch(1)`, and `git-send-email(1)` directly.
+
+        `rake mail_patches` handles setting the appropriate flags to
+        `git-format-patch(1)` and `git-send-email(1)` for you, but
+        doesn't allow adding any commentary between the '---', and the
+        diffstat in the resulting email.  It also requires that you
+        have created your topic branch in the form
+        `<type>/<parent>/<name>`.
+
+        If you decide to use `git-format-patch(1)` and
+        `git-send-email(1)` directly, please be sure to use the
+        following flags for `git-format-patch(1)`: -C -M -s -n
+        --subject-prefix='PATCH/puppet'
+
+      * Attaching patches to Redmine
+
+        As a method of last resort you can also directly attach the
+        output of `git-format-patch(1)`, or `git-diff(1)` to a Redmine
+        ticket.
+
+        If you are generating the diff outside of Git, please be sure
+        to generate a unified diff.
+
+  4.  Update the related Redmine ticket.
+
+      If there's a Redmine ticket associated with the change you
+      submitted, then you should update the ticket to include the
+      location of your branch, and change the status to "In Topic
+      Branch Pending Merge", along with any other commentary you may
+      wish to make.
+
+How to track the status of your change after it's been submitted
+================================================================
+
+Shortly after opening a pull request on GitHub, there should be an
+automatic message sent to the puppet-dev Google Groups mailing list
+notifying people of this.  This notification is used to let the Puppet
+development community know about your requested change to give them a
+chance to review, test, and comment on the change(s).
+
+If you submitted your change via manually sending a pull request or
+mailing the patches, then we keep track of these using
+[patchwork](https://patchwork.puppetlabs.com).  When code is merged
+into the project it is automatically removed from patchwork, and the
+Redmine ticket is manually updated with the commit SHA1.  In addition,
+the ticket status must be updated by the person who merges the topic
+branch to a status of "Merged - Pending Release"
+
+We do our best to comment on or merge submitted changes within a week.
+However, if there hasn't been any commentary on the pull request or
+mailed patches, and it hasn't been merged in after a week, then feel
+free to ask for an update by replying on the mailing list to the
+automatic notification or mailed patches. It probably wasn't
+intentional, and probably just slipped through the cracks.
+
+Additional Resources
+====================
+
+* [Getting additional help](http://projects.puppetlabs.com/projects/puppet/wiki/Getting_Help)
+
+* [Writing tests](http://projects.puppetlabs.com/projects/puppet/wiki/Development_Writing_Tests)
+
+* [Bug tracker (Redmine)](http://projects.puppetlabs.com)
+
+* [Patchwork](https://patchwork.puppetlabs.com)
+
+* [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
+
+* [General GitHub documentation](http://help.github.com/)
+
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+
+If you have commit access to the repository
+===========================================
+
+Even if you have commit access to the repository, you'll still need to
+go through the process above, and have someone else review and merge
+in your changes.  The rule is that all changes must be reviewed by a
+developer on the project (that didn't write the code) to ensure that
+all changes go through a code review process.
+
+Having someone other than the author of the topic branch recorded as
+performing the merge is the record that they performed the code
+review.
+
+  * Merging topic branches
+
+    When merging code from a topic branch into the integration branch
+    (Ex: master, 2.7.x, 1.6.x, etc.), there should always be a merge
+    commit.  You can accomplish this by always providing the `--no-ff`
+    flag to `git merge`.
+
+        git merge --no-ff --log tickets/master/1234-fix-something-broken
+
+    The reason for always forcing this merge commit is that it
+    provides a consistent way to look up what changes & commits were
+    in a topic branch, whether that topic branch had one, or 500
+    commits.  For example, if the merge commit had an abbreviated
+    SHA-1 of `coffeebad`, then you could use the following `git log`
+    invocation to show you which commits it brought in:
+
+        git log coffeebad^1..coffeebad^2
+
+    The following would show you which changes were made on the topic
+    branch:
+
+        git diff coffeebad^1...coffeebad^2
+
+    Because we _always_ merge the topic branch into the integration
+    branch the first parent (`^1`) of a merge commit will be the most
+    recent commit on the integration branch from just before we merged
+    in the topic, and the second parent (`^2`) will always be the most
+    recent commit that was made in the topic branch.  This also serves
+    as the record of who performed the code review, as mentioned
+    above.