puppet 2.7.19 → 2.7.20.rc1

data/CONTRIBUTING.md

@@ -1,242 +1,65 @@
-Checklist/Outline (The short version)
-=================================================
-
-  * Getting Started: 
-    - Make sure you have a [Redmine account](http://projects.puppetlabs.com)
-    - Submit a ticket for your issue, assuming one does not already exist. 
-    - Decide what to base your work off of 
-      * `2.6.x`: security fixes only
-      * `2.7.x`: bug fixes only
-      * `3.x`: new features that are not breaking changes
-      * `master`: new features that are breaking changes 
-    
-  * Making Changes: 
-     - Make sure you have a [GitHub account](https://github.com/signup/free)
-     - Fork the repository on GitHub
-     - Make commits of logical units.
-     - Check for unnecessary whitespace with "git diff --check" before committing.
-     - Make sure your commit messages are in the proper format 
-     - Make sure you have added the necessary tests for your changes
-     - Run _all_ the tests to assure nothing else was accidentally broken 
-
-  * Submitting Changes: 
-     - Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
-     -  Push your changes to a topic branch in your fork of the repository.
-     -  Submit a pull request to the repository in the puppetlabs organization.
-     -  Update your Redmine ticket 
-   
-The long version
-================
-
-  0. Create a Redmine ticket for the change you'd like to make.
-     
-	 It's very important that there be a Redmine ticket for the change 
-	 you are making. Considering the number of contributions which are 
-	 submitted, it is crucial that we know we can find the ticket on Redmine.
-	
-	 Before making a ticket however, be sure that one does not already exist.
-	 You can do this by searching Redmine or by trying a Google search which 
-	 includes `sites:projects.puppetlabs.com` in addition to some of the keywords 
-	 related to your issue. 
-	
-	 If you do not find a ticket that that accurately describes the work 
-	 you're going to be doing, go ahead and create one. But be sure to 
-	 look for related tickets and add them to the 'related tickets' section.
-
-  1.  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, and it will be 
-	  eventually merged up. Currently, branches will be merged up as 
-	  follows: 
-	    2.6.x => 2.7.x => 3.x => master 
-	
-	  Currently, this is how you should decide where to target your changes: 
-	
-	  The absolute earliest place something should be targeted is at `2.6.x`, 
-	    and these should _only_ be security fixes. Anything else must be
-	    targeted at a later branch.
-	
-	  A bug fix should be based off the the earliest place where it is 
-		relevant. If it first appears in `2.7.x`, then it should be 
-		targeted here and eventually merged up to `3.x` and master. 
-		
-	  New features which are _backwards compatible_ should be targeted 
-	    at the next release, which currently is `3.x`. 
-	
-	  New features that are _breaking changes_ should be targeted at 
-		`master`.
-
-      Part of deciding what to what your work should be based off of includes naming 
-	  your topic branch to reflect this. Your branch name should have the following 
-	  format: 
-	  		`ticket/target_branch/ticket_number_short_description_of_issuee` 
-	
-	  For example, if you are fixing a bug relating to the ssl spec, which has Redmine 
-	  ticket number 12345, then your branch should be named: 
-			`ticket/2.7.x/12345_fix_ssl_spec_tests` 
-			
-	  There is a good chance that if you submit a pull request _from_ master _to_ master, 
-	  Puppet Labs developers will suspect that you're not sure about the process. This is 
-	  why clear naming of branches and basing your work off the right place will be 
-	  extremely helpful in ensuring that your submission is reviewed and merged. Often times
-	  if your change is targeted at the wrong place, we will bounce it back to you and wait 
-	  to review it until it has been retargeted. 
-
-  2.  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.
-
-      It's crucial that your changes 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.
-
-      When writing commit messages, please be sure they meet 
-	  [these standards](https://github.com/erlang/otp/wiki/Writing-good-commit-messages), and please include the ticket number in your 
-	  short summary. It should look something like this: `(#12345) Fix this issue in Puppet`
-
-  3.  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.
-
-  4.  Sending your patches
-
-      To submit your changes via a GitHub pull request, you must
-      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.
-
-  5.  Update the related Redmine ticket.
-
-      You should update the Redmine ticket associated 
-      with the change you submitted to include the location of your branch
-      on the `branch` field of the ticket, and change the status to 
-      "In Topic Branch Pending Review", 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, there should be an automatic 
-email sent via GitHub. 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).
-
-We do our best to comment on or merge submitted changes within a about 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)
-
+# How to contribute
+
+Third-party patches are essential for keeping puppet great. We simply can't
+access the huge number of platforms and myriad configurations for running
+puppet. We want to keep it as easy as possible to contribute changes that
+get things working in your environment. There are a few guidelines that we
+need contributors to follow so that we can have a chance of keeping on
+top of things.
+
+## Getting Started
+
+* Make sure you have a [Redmine account](http://projects.puppetlabs.com)
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a ticket for your issue, assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+  * This is usually the master branch.
+  * Only target release branches if you are certain your fix must be on that
+    branch.
+  * To quickly create a topic branch based on master; `git branch
+    fix/master/my_contribution master` then checkout the new branch with `git
+    checkout fix/master/my_contribution`.  Please avoid working directly on the
+    `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+
+````
+    (#99999) Make the example in CONTRIBUTING imperative and concrete
+
+    Without this patch applied the example commit message in the CONTRIBUTING
+    document is not a concrete example.  This is a problem because the
+    contributor is left to imagine what the commit message should look like
+    based on a description rather than an example.  This patch fixes the
+    problem by making the example concrete and imperative.
+
+    The first line is a real life imperative statement with a ticket number
+    from our issue tracker.  The body describes the behavior without the patch,
+    why this is a problem, and how the patch fixes the problem when applied.
+````
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Submitting Changes
+
+* Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign).
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the puppetlabs organization.
+* Update your Redmine ticket to mark that you have submitted code and are ready for it to be reviewed.
+  * Include a link to the pull request in the ticket
+
+# Additional Resources
+
+* [More information on contributing](http://links.puppetlabs.com/contribute-to-puppet)
 * [Bug tracker (Redmine)](http://projects.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.
+* #puppet-dev IRC channel on freenode.org

data/Gemfile

@@ -0,0 +1,32 @@
+source :rubygems
+
+gemspec
+
+group(:development, :test) do
+  gem "facter", "~> 1.6.4", :require => false
+  gem "rack", "~> 1.4.1", :require => false
+  gem "rspec", "~> 2.10.0", :require => false
+  gem "mocha", "~> 0.10.5", :require => false
+end
+
+platforms :mswin, :mingw do
+  # See http://jenkins.puppetlabs.com/ for current Gem listings for the Windows
+  # CI Jobs.
+  gem "sys-admin", "~> 1.5.6", :require => false
+  gem "win32-api", "~> 1.4.8", :require => false
+  gem "win32-dir", "~> 0.3.7", :require => false
+  gem "win32-eventlog", "~> 0.5.3", :require => false
+  gem "win32-process", "~> 0.6.5", :require => false
+  gem "win32-security", "~> 0.1.4", :require => false
+  gem "win32-service", "~> 0.7.2", :require => false
+  gem "win32-taskscheduler", "~> 0.2.2", :require => false
+  gem "win32console", "~> 1.3.2", :require => false
+  gem "windows-api", "~> 0.4.1", :require => false
+  gem "windows-pr", "~> 1.2.1", :require => false
+end
+
+if File.exists? "#{__FILE__}.local"
+  eval(File.read("#{__FILE__}.local"), binding)
+end
+
+# vim:filetype=ruby

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    puppet (2.7.19)
+      facter (~> 1.5)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    facter (1.6.11)
+    metaclass (0.0.1)
+    mocha (0.10.5)
+      metaclass (~> 0.0.1)
+    rack (1.4.1)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  facter (~> 1.6.4)
+  mocha (~> 0.10.5)
+  puppet!
+  rack (~> 1.4.1)
+  rspec (~> 2.10.0)
+  sys-admin (~> 1.5.6)
+  win32-api (~> 1.4.8)
+  win32-dir (~> 0.3.7)
+  win32-eventlog (~> 0.5.3)
+  win32-process (~> 0.6.5)
+  win32-security (~> 0.1.4)
+  win32-service (~> 0.7.2)
+  win32-taskscheduler (~> 0.2.2)
+  win32console (~> 1.3.2)
+  windows-api (~> 0.4.1)
+  windows-pr (~> 1.2.1)

data/LICENSE

@@ -1,6 +1,6 @@
    Puppet - Automating Configuration Management.
 
-   Copyright (C) 2011 Puppet Labs Inc
+   Copyright (C) 2005-2012 Puppet Labs Inc
 
    Puppet Labs can be contacted at: info@puppetlabs.com
 

data/README_DEVELOPER.md

@@ -3,6 +3,203 @@
 This file is intended to provide a place for developers and contributors to
 document what other developers need to know about changes made to Puppet.
 
+# Use of RVM considered dangerous #
+
+Use of RVM in production situations, e.g. running CI tests against this
+repository, is considered dangerous.  The reason we consider RVM to be
+dangerous is because the default behavior of RVM is to hijack the builtin
+behavior of the shell, causing Gemfile files to be loaded and evaluated when
+the shell changes directories into the project root.
+
+This behavior causes the CI Job execution environment that runs with `set -e`
+to be incompatible with RVM.
+
+We work around this issue by disabling the per-project RC file parsing using
+
+    if ! grep -qx rvm_project_rvmrc=0 ~/.rvmrc; then
+      echo rvm_project_rvmrc=0 >> ~/.rvmrc
+    fi
+
+When we setup CI nodes, but this is not standard or expected behavior.
+
+Please consider rbenv instead of rvm.  The default behavior of rvm is difficult
+to maintain with `set -e` shell environments.
+
+# Two Types of Catalog
+
+When working on subsystems of Puppet that deal with the catalog it is important
+to be aware of the two different types of Catalog.  I often ran into this when
+working in Professional Services when I built a small tool to diff two catalogs
+to determine if an upgrade in Puppet produces the same configuration catalogs.
+As a developer I've run into this difference while working on spec tests for
+the static compiler and working on spec tests for types and providers.
+
+The two different types of catalog becomes relevant when writing spec tests
+because we frequently need to wire up a fake catalog so that we can exercise
+types, providers, or terminii that filter the catalog.
+
+The two different types of catalogs are so-called "resource" catalogs and "RAL"
+(resource abstraction layer) catalogs.  At a high level, the resource catalog
+is the in-memory object we serialize and transfer around the network.  The
+compiler terminus is expected to produce a resource catalog.  The agent takes a
+resource catalog and converts it into a RAL catalog.  The RAL catalog is what
+is used to apply the configuration model to the system.
+
+Resource dependency information is most easily obtained from a RAL catalog by
+walking the graph instance produced by the `relationship_graph` method.
+
+## Resource Catalog
+
+If you're writing spec tests for something that deals with a catalog "server
+side," a new catalog terminus for example, then you'll be dealing with a
+resource catalog.  You can produce a resource catalog suitable for spec tests
+using something like this:
+
+    let(:catalog) do
+      catalog = Puppet::Resource::Catalog.new("node-name-val") # NOT certname!
+      rsrc = Puppet::Resource.new("file", "sshd_config",
+        :parameters => {
+          :ensure => 'file',
+          :source => 'puppet:///modules/filetest/sshd_config',
+        }
+      )
+      rsrc.file = 'site.pp'
+      rsrc.line = 21
+      catalog.add_resource(rsrc)
+    end
+
+The resources in this catalog may be accessed using `catalog.resources`.
+Resource dependencies are not easily walked using a resource catalog however.
+To walk the dependency tree convert the catalog to a RAL catalog as described
+in
+
+## RAL Catalog
+
+The resource catalog may be converted to a RAL catalog using `catalog.to_ral`.
+The RAL catalog contains `Puppet::Type` instances instead of `Puppet::Resource`
+instances as is the case with the resource catalog.
+
+One very useful feature of the RAL catalog are the methods to work with
+resource relationships.  For example:
+
+    irb> catalog = catalog.to_ral
+    irb> graph = catalog.relationship_graph
+    irb> pp graph.edges
+    [{ Notify[alpha] => File[/tmp/file_20.txt] },
+     { Notify[alpha] => File[/tmp/file_21.txt] },
+     { Notify[alpha] => File[/tmp/file_22.txt] },
+     { Notify[alpha] => File[/tmp/file_23.txt] },
+     { Notify[alpha] => File[/tmp/file_24.txt] },
+     { Notify[alpha] => File[/tmp/file_25.txt] },
+     { Notify[alpha] => File[/tmp/file_26.txt] },
+     { Notify[alpha] => File[/tmp/file_27.txt] },
+     { Notify[alpha] => File[/tmp/file_28.txt] },
+     { Notify[alpha] => File[/tmp/file_29.txt] },
+     { File[/tmp/file_20.txt] => Notify[omega] },
+     { File[/tmp/file_21.txt] => Notify[omega] },
+     { File[/tmp/file_22.txt] => Notify[omega] },
+     { File[/tmp/file_23.txt] => Notify[omega] },
+     { File[/tmp/file_24.txt] => Notify[omega] },
+     { File[/tmp/file_25.txt] => Notify[omega] },
+     { File[/tmp/file_26.txt] => Notify[omega] },
+     { File[/tmp/file_27.txt] => Notify[omega] },
+     { File[/tmp/file_28.txt] => Notify[omega] },
+     { File[/tmp/file_29.txt] => Notify[omega] }]
+
+If the `relationship_graph` method is throwing exceptions at you, there's a
+good chance the catalog is not a RAL catalog.
+
+## Settings Catalog ##
+
+Be aware that Puppet creates a mini catalog and applies this catalog locally to
+manage file resource from the settings.  This behavior made it difficult and
+time consuming to track down a race condition in
+[2888](http://projects.puppetlabs.com/issues/2888).
+
+Even more surprising, the `File[puppetdlockfile]` resource is only added to the
+settings catalog if the file exists on disk.  This caused the race condition as
+it will exist when a separate process holds the lock while applying the
+catalog.
+
+It may be sufficient to simply be aware of the settings catalog and the
+potential for race conditions it presents.  An effective way to be reasonably
+sure and track down the problem is to wrap the File.open method like so:
+
+    # We're wrapping ourselves around the File.open method.
+    # As described at: http://goo.gl/lDsv6
+    class File
+      WHITELIST = [ /pidlock.rb:39/ ]
+
+      class << self
+        alias xxx_orig_open open
+      end
+
+      def self.open(name, *rest, &block)
+        # Check the whitelist for any "good" File.open calls against the #
+        puppetdlock file
+        white_listed = caller(0).find do |line|
+          JJM_WHITELIST.find { |re| re.match(line) }
+        end
+
+        # If you drop into IRB here, take a look at your caller, it might be
+        # the ghost in the machine you're looking for.
+        binding.pry if name =~ /puppetdlock/ and not white_listed
+        xxx_orig_open(name, *rest, &block)
+      end
+    end
+
+The settings catalog is populated by the `Puppet::Util::Settings#to\_catalog`
+method.
+
+# Ruby Dependencies #
+
+Puppet is considered an Application as it relates to the recommendation of
+adding a Gemfile.lock file to the repository and the information published at
+[Clarifying the Roles of the .gemspec and
+Gemfile](http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/)
+
+To install the dependencies run: `bundle install` to install the dependencies.
+
+A checkout of the source repository should be used in a way that provides
+puppet as a gem rather than a simple Ruby library.  The parent directory should
+be set along the `GEM_PATH`, preferably before other tools such as RVM that
+manage gemsets using `GEM_PATH`.
+
+For example, Puppet checked out into `/workspace/src/puppet` using `git
+checkout https://github.com/puppetlabs/puppet` in `/workspace/src` can be used
+with the following actions.  The trick is to symlink `gems` to `src`.
+
+    $ cd /workspace
+    $ ln -s src gems
+    $ mkdir specifications
+    $ pushd specifications; ln -s ../gems/puppet/puppet.gemspec; popd
+    $ export GEM_PATH="/workspace:${GEM_PATH}"
+    $ gem list puppet
+
+This should list out
+
+    puppet (2.7.19)
+
+## Bundler ##
+
+With a source checkout of Puppet properly setup as a gem, dependencies can be
+installed using [Bundler](http://gembundler.com/)
+
+    $ bundle install
+    Fetching gem metadata from http://rubygems.org/........
+    Using diff-lcs (1.1.3)
+    Installing facter (1.6.11)
+    Using metaclass (0.0.1)
+    Using mocha (0.10.5)
+    Using puppet (2.7.19) from source at /workspace/puppet-2.7.x/src/puppet
+    Using rack (1.4.1)
+    Using rspec-core (2.10.1)
+    Using rspec-expectations (2.10.0)
+    Using rspec-mocks (2.10.1)
+    Using rspec (2.10.0)
+    Using bundler (1.1.5)
+    Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
+
 # UTF-8 Handling #
 
 As Ruby 1.9 becomes more commonly used with Puppet, developers should be aware
@@ -89,10 +286,10 @@ Puppet directly from source without using install.rb or copying files around.
 ## Common Issues ##
 
  * Don't assume file paths start with '/', as that is not a valid path on
-   Windows.  Use Puppet::Util.absolute_path? to validate that a path is fully
+   Windows.  Use Puppet::Util.absolute\_path? to validate that a path is fully
    qualified.
 
- * Use File.expand_path('/tmp') in tests to generate a fully qualified path
+ * Use File.expand\_path('/tmp') in tests to generate a fully qualified path
    that is valid on POSIX and Windows.  In the latter case, the current working
    directory will be used to expand the path.
 
@@ -108,11 +305,11 @@ Puppet directly from source without using install.rb or copying files around.
 
      IO.open(path, 'rb')
 
- * Don't assume file paths are separated by ':'.  Use File::PATH_SEPARATOR
+ * Don't assume file paths are separated by ':'.  Use `File::PATH_SEPARATOR`
    instead, which is ':' on POSIX and ';' on Windows.
 
- * On Windows, File::SEPARATOR is '/', and File::ALT_SEPARATOR is '\'.  On
-   POSIX systems, File::ALT_SEPARATOR is nil.  In general, use '/' as the
+ * On Windows, File::SEPARATOR is '/', and `File::ALT_SEPARATOR` is '\'.  On
+   POSIX systems, `File::ALT_SEPARATOR` is nil.  In general, use '/' as the
    separator as most Windows APIs, e.g. CreateFile, accept both types of
    separators.
 
@@ -123,4 +320,102 @@ Puppet directly from source without using install.rb or copying files around.
  * Don't assume 'C' drive.  Use environment variables to look these up:
 
     "#{ENV['windir']}/system32/netsh.exe"
+
+# Determining the Puppet Version
+
+If you need to programmatically work with the Puppet version, please use the
+following:
+
+    require 'puppet/version'
+    # Get the version baked into the sourcecode:
+    version = Puppet.version
+    # Set the version (e.g. in a Rakefile based on `git describe`)
+    Puppet.version = '2.3.4'
+
+Please do not monkey patch the constant `Puppet::PUPPETVERSION` or obtain the
+version using the constant.  The only supported way to set and get the Puppet
+version is through the accessor methods.
+
+# Static Compiler
+
+The static compiler was added to Puppet in the 2.7.0 release.
+[1](http://links.puppetlabs.com/static-compiler-announce)
+
+The static compiler is intended to provide a configuration catalog that
+requires a minimal amount of network communication in order to apply the
+catalog to the system.  As implemented in Puppet 2.7.x and Puppet 3.0.x this
+intention takes the form of replacing all of the source parameters of File
+resources with a content parameter containing an address in the form of a
+checksum.  The expected behavior is that the process applying the catalog to
+the node will retrieve the file content from the FileBucket instead of the
+FileServer.
+
+The high level approach can be described as follows.  The `StaticCompiler` is a
+terminus that inserts itself between the "normal" compiler terminus and the
+request.  The static compiler takes the resource catalog produced by the
+compiler and filters all File resources.  Any file resource that contains a
+source parameter with a value starting with 'puppet://' is filtered in the
+following way in a "standard" single master / networked agents deployment
+scenario:
+
+ 1. The content, owner, group, and mode values are retrieved from th
+     FileServer by the master.
+ 2. The file content is stored in the file bucket on the master.
+ 3. The source parameter value is stripped from the File resource.
+ 4. The content parameter value is set in the File resource using the form
+    '{XXX}1234567890' which can be thought of as a content address indexed by
+    checksum.
+ 5. The owner, group and mode values are set in the File resource if they are
+    not already set.
+ 6. The filtered catalog is returned in the response.
+
+In addition to the catalog terminus, the process requesting the catalog needs
+to obtain the file content.  The default behavior of `puppet agent` is to
+obtain file contents from the local client bucket.  The method we expect users
+to employ to reconfigure the agent to use the server bucket is to declare the
+`Filebucket[puppet]` resource with the address of the master. For example:
+
+    node default {
+      filebucket { puppet:
+        server => $server,
+        path   => false,
+      }
+      class { filetest: }
+    }
+
+This special filebucket resource named "puppet" will cause the agent to fetch
+file contents specified by checksum from the remote filebucket instead of the
+default clientbucket.
+
+## Quick start
+
+Create a module that recursively downloads something.  The jeffmccune-filetest
+module will recursively copy the rubygems source tree.
+
+    $ puppet module install jeffmccune-filetest
+
+Start the master with the StaticCompiler turned on:
+
+    $ puppet master \
+        --catalog_terminus=static_compiler \
+        --verbose \
+        --no-daemonize
+
+Add the special Filebucket[puppet] resource:
+
+    # site.pp
+    node default {
+      filebucket { puppet: server => $server, path => false }
+      class { filetest: }
+    }
+
+Get the static catalog:
+
+    $ puppet agent --test
+
+You should expect all file metadata to be contained in the catalog, including a
+checksum representing the content.  When managing an out of sync file resource,
+the real contents should be fetched from the server instead of the
+clientbucket.
+
 EOF