Merge branch 'stable'

Conflicts:
	acceptance/tests/modules/install/with_version.rb
	Resolved in favor of MASTER

CONTRIBUTING.md

@@ -73,7 +73,7 @@ for advice.
 For changes of a trivial nature to comments and documentation, it is not
 always necessary to create a new ticket in Jira. In this case, it is
 appropriate to start the first line of a commit with '(doc)' instead of
-a ticket number. 
+a ticket number.
 
 ````
     (doc) Add documentation commit example to CONTRIBUTING
@@ -83,7 +83,7 @@ a ticket number.
     is left to assume how a commit of this nature may appear.
 
     The first line is a real life imperative statement with '(doc)' in
-    place of what would have been the ticket number in a 
+    place of what would have been the ticket number in a
     non-documentation related commit. The body describes the nature of
     the new documentation or comments added.
 ````
@@ -97,15 +97,20 @@ a ticket number.
   * Include a link to the pull request in the ticket.
 * The core team looks at Pull Requests on a regular basis in a weekly triage
   meeting that we hold in a public Google Hangout. The hangout is announced in
-  the weekly status updates that are sent to the puppet-dev list.
+  the weekly status updates that are sent to the puppet-dev list. Notes are
+  posted to the [Puppet Community community-triage
+  repo](https://github.com/puppet-community/community-triage/tree/master/core/notes)
+  and include a link to a YouTube recording of the hangout.
 * After feedback has been given we expect responses within two weeks. After two
-  weeks will may close the pull request if it isn't showing any activity.
+  weeks we may close the pull request if it isn't showing any activity.
 
 # Additional Resources
 
-* [More information on contributing](http://links.puppetlabs.com/contribute-to-puppet)
+* [Puppet Labs community guildelines](http://docs.puppetlabs.com/community/community_guidelines.html)
 * [Bug tracker (Jira)](http://tickets.puppetlabs.com)
 * [Contributor License Agreement](http://links.puppetlabs.com/cla)
 * [General GitHub documentation](http://help.github.com/)
 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
-* #puppet-dev IRC channel on freenode.org
+* #puppet-dev IRC channel on freenode.org ([Archive](https://botbot.me/freenode/puppet-dev/))
+* [puppet-dev mailing list](https://groups.google.com/forum/#!forum/puppet-dev)
+* [Community PR Triage notes](https://github.com/puppet-community/community-triage/tree/master/core/notes)

lib/puppet/defaults.rb

@@ -452,10 +452,33 @@ def self.default_diffargs
     :environment_timeout => {
       :default    => "0",
       :type       => :ttl,
-      :desc       => "The time to live for a cached environment.
+      :desc       => "How long the Puppet master should cache data it loads from an
+      environment.
       #{AS_DURATION}
-      This setting can also be set to `unlimited`, which causes the environment to
-      be cached until the master is restarted."
+      A value of `0` will disable caching. This setting can also be set to
+      `unlimited`, which will cache environments until the master is restarted
+      or told to refresh the cache.
+
+      You should change this setting once your Puppet deployment is doing
+      non-trivial work. We chose the default value of `0` because it lets new
+      users update their code without any extra steps, but it lowers the
+      performance of your Puppet master.
+
+      We recommend setting this to `unlimited` and explicitly refreshing your
+      Puppet master as part of your code deployment process.
+
+      * With Puppet Server, you should refresh environments by calling the
+        `environment-cache` API endpoint. See the docs for the Puppet Server
+        administrative API.
+      * With a Rack Puppet master, you should restart the web server or the
+        application server. Passenger lets you touch a `restart.txt` file to
+        refresh an application without restarting Apache; see the Passenger docs
+        for details.
+
+      We don't recommend using any value other than `0` or `unlimited`, since
+      most Puppet masters use a pool of Ruby interpreters which all have their
+      own cache timers. When these timers drift out of sync, agents can be served
+      inconsistent catalogs."
     },
     :environment_data_provider => {
       :default    => "none",

lib/puppet/error.rb

@@ -54,6 +54,10 @@ class ResourceError < Puppet::Error
     include ExternalFileError
   end
 
+  # An error that already contains location information in the message text
+  class PreformattedError < Puppet::ParseError
+  end
+
   # An error class for when I don't know what happened.  Automatically
   # prints a stack trace when in debug mode.
   class DevError < Puppet::Error

lib/puppet/pops/evaluator/evaluator_impl.rb

@@ -70,14 +70,43 @@ def evaluate(target, scope)
       @@eval_visitor.visit_this_1(self, target, scope)
 
     rescue Puppet::Pops::SemanticError => e
-      # a raised issue may not know the semantic target
+      # A raised issue may not know the semantic target, use errors call stack, but fill in the 
+      # rest from a supplied semantic object, or the target instruction if there is not semantic
+      # object.
+      #
       fail(e.issue, e.semantic || target, e.options, e)
 
-    rescue StandardError => e
-      if e.is_a? Puppet::ParseError
-        # ParseError's are supposed to be fully configured with location information
+    rescue Puppet::PreformattedError => e
+      # Already formatted with location information, and with the wanted call stack.
+      # Note this is currently a specialized ParseError, so rescue-order is important
+      #
+      raise e
+
+    rescue Puppet::ParseError => e
+      # ParseError may be raised in ruby code without knowing the location
+      # in puppet code.
+      # Accept a ParseError that has file or line information available
+      # as an error that should be used verbatim. (Tests typically run without
+      # setting a file name).
+      # ParseError can supply an original - it is impossible to determine which
+      # call stack that should be propagated, using the ParseError's backtrace.
+      #
+      if e.file || e.line
         raise e
+      else
+        # Since it had no location information, treat it as user intended a general purpose
+        # error. Pass on its call stack.
+        fail(Issues::RUNTIME_ERROR, target, {:detail => e.message}, e)
       end
+
+
+    rescue Puppet::Error => e
+      # PuppetError has the ability to wrap an exception, if so, use the wrapped exception's
+      # call stack instead
+      fail(Issues::RUNTIME_ERROR, target, {:detail => e.message}, e.original || e)
+
+    rescue StandardError => e
+      # All other errors, use its message and call stack
       fail(Issues::RUNTIME_ERROR, target, {:detail => e.message}, e)
     end
   end

lib/puppet/pops/evaluator/runtime3_support.rb

@@ -470,7 +470,11 @@ def initialize
   class ExceptionRaisingAcceptor < Puppet::Pops::Validation::Acceptor
     def accept(diagnostic)
       super
-      Puppet::Pops::IssueReporter.assert_and_report(self, {:message => "Evaluation Error:", :emit_warnings => true })
+      Puppet::Pops::IssueReporter.assert_and_report(self, {
+        :message => "Evaluation Error:", 
+        :emit_warnings => true,  # log warnings
+        :exception_class => Puppet::PreformattedError
+      })
       if errors?
         raise ArgumentError, "Internal Error: Configuration of runtime error handling wrong: should have raised exception"
       end

lib/puppet/util/errors.rb

@@ -14,7 +14,7 @@ def devfail(msg)
   # Add line and file info to the supplied exception if info is available from
   # this object, is appropriately populated and the supplied exception supports
   # it.  When other is supplied, the backtrace will be copied to the error
-  # object.
+  # object and the 'original' will be dropped from the error.
   #
   # @param error [Exception] exception that is populated with info
   # @param other [Exception] original exception, source of backtrace info
@@ -25,7 +25,9 @@ def adderrorcontext(error, other = nil)
     error.original ||= other if error.respond_to?(:original=)
 
     error.set_backtrace(other.backtrace) if other and other.respond_to?(:backtrace)
-
+    # It is not meaningful to keep the wrapped exception since its backtrace has already
+    # been adopted by the error. (The instance variable is private for good reasons).
+    error.instance_variable_set(:@original, nil)
     error
   end