(doc) Document key purging in the description of the ssh_authorized_key type

This commit puts an explanation of key purging over where people will likely be
looking for it. It also tightens up the description of the user type's
purge_ssh_keys attribute, and adds an example key to the ssh_authorized_key type
(since the way that type breaks up key lines is somewhat unintuitive).

The example public key is a dud, to prevent accidental access grants.
(PUP-2311) OpenBSD uninstall broken when multiple uninstall_options given
(PUP-2458) Tests for providers inheriting from providers of another type

It's sometimes desirable to create new providers that inherit from providers
of a different type to create more specialised types/providers from a common
base.  This adds tests around this already-present functionality.
(PUP-2508) Ensure env & trn-uuid are sent when configurer failures occur

Any failure in the configurer #run code might cause the ensure block to
evaluate early, and a report might be sent missing the details of what
the environment and transaction_uuid should be.

This patch moves where the report fields 'environment' and
'transaction_uuid' are set in the configurer code to ensure they are
populated early.

It also ensures the report environment is modified if the catalog or
server specifies it is different to the launched environment. This is
because we change this mid-flight, so our code simplies updates the
report environment when this happens.

Signed-off-by: Ken Barber <ken@bob.sh>
(PUP-2182) Add virtual_packages feature to package type.

In 3.5.x, the yum package provider changed to accept virtual package
names (packages that provide other package names).

That change in behavior caused some undesirable side-effects. As we did
not give users fair warning that this behavior was changing, we have
decided to change the yum provider back to only accepting "real" package
names by default.

To keep the support for virtual package names, a "virtual_packages"
feature has been implemented on the package type and supported on the
yum package provider.  The feature adds the "allow_virtual" parameter
that controls whether or not virtual package names will be allowed for
install/uninstall.

For now, the default value for this parameter will be false to restore
the previous behavior.  However, a deprecation warning will be issued to
let users know that the default will eventually be changed to true.
Users can prevent the deprecation warning by explicitly setting the
parameter to either true or false.
Merge pull request #2563 from jasperla/openbsd/uninstall

(PUP-2311) OpenBSD uninstall broken when multiple uninstall_options give
Merge pull request #2606 from nfagerlund/docs_ssh_key_purge

(doc) Document key purging in the description of the ssh_authorized_key ...
Merge pull request #2615 from domcleal/tickets/master/pup-2458-inherit-providers

(PUP-2458) Tests for providers inheriting from providers of another type
(PUP-1027) Add warnings for bare words that will be keywords in 4.0

This adds a check for reserved words and makes the words:
private, function, type, and attr reserved.

These warnings are for the --parser current setting in 3x.
(PUP-1027) Change warning for reserved words to a deprecation warning
(PUP-1027) Make it an error to use reserved words in future parser.

This makes it an error to use the reserved words function, private,
attr, and type in the future parser. The same keywords issue warnings
in 3x that they must be quoted. Therefore, the 4x implementation should
make it an error to use them (until there is support for the features
they will represent). If these are not made in to errors the features
can not be introduced without breakage since a deprecation can only be
turned into an error (or something new) in a major release.
(PUP-1027) Improve warning message for reserved words

The original warning about reserved words implied that a user could
always quote the word to be able to use this. Although this is often the
case there are also places where the word is used as a NAME (such as
class function {}) where quoting is not an option. In those cases they
need to select a different name.
(packaging) Update PUPPETVERSION to 3.6.0
Merge pull request #2640 from peterhuene/pup/2182

(PUP-2182) Add virtual_packages feature to package type.
(PUP-2182) Add virtual_packages feature to package type.

In 3.5.x, the yum package provider changed to accept virtual package
names (packages that provide other package names).

That change in behavior caused some undesirable side-effects. As we did
not give users fair warning that this behavior was changing, we have
decided to change the yum provider back to only accepting "real" package
names by default.

To keep the support for virtual package names, a "virtual_packages"
feature has been implemented on the package type and supported on the
yum package provider.  The feature adds the "allow_virtual" parameter
that controls whether or not virtual package names will be allowed for
install/uninstall.

For now, the default value for this parameter will be false to restore
the previous behavior.  However, a deprecation warning will be issued to
let users know that the default will eventually be changed to true.
Users can prevent the deprecation warning by explicitly setting the
parameter to either true or false.
(maint) Fix latent error in parser face

There was an error when the spec/unit/util/rdoc_spec.rb tests were run
before the spec/unit/face/parser_spec.rb tests. In that order the test
for the "parser validate" action would fail when it is supposed to read
text from stdin.

What occured was that the environment from the previous test had created
a @known_resource_types on the current_environment. When the face ran it
didn't make sure that the environment was reset before trying to
validate the code it was given. The validation is done in a very
round-about manner where simply asking the environment for the
known_resource_types is expected to result in perform_initial_import,
which will raise and error if there are syntax errors in the manifest.
However, since the environment already had a @known_resource_types
value, it skipped perform_initial_import and didn't fail as the test
expected.

The fix is to ensure that the environment will reparse the manifests if
needed, which required a small adjustment to the reparse logic on the
environment, since the watching? flag should only control file watching,
not changes to the code setting. The other part is to have the validate
face check that it needs to reparse before assuming that
known_resource_types will automatically cause a parse to occur.

This is still a very awkward way to validate syntax, but it perhaps
slightly better now.
Merge branch 'pr/2636'

* pr/2636:
  (maint) Fix latent error in parser face
  (PUP-1027) Improve warning message for reserved words
  (PUP-1027) Make it an error to use reserved words in future parser.
  (PUP-1027) Change warning for reserved words to a deprecation warning
  (PUP-1027) Add warnings for bare words that will be keywords in 4.0
(PUP-2031) Fix broken range support in unless_uid parameter.

The unless_uid parameter on the resources type attempts to support
ranges, but the implementation is expecting ruby Range types during
munging, which the current parser implementation will not produce.

Additionally, it tries to parse strings of "[x,y]" and "[x..y]" as
ranges but fails to properly remove the brackets and fails to
munge the value.

As there is currently no way to efficiently represent a range for this
parameter, we've decided to back out this broken support for ranges and
instead limit the unless_uid values to integers, integer strings, and
arrays of integers or integer strings.

Users that want to use a range will have to make use of the stdlib
range() function, which is what they have to do currently given the
range support was broken.

In Puppet 4.x, we should look to making use of the future parser's
support for ranges in the Puppet language for this parameter.
(PUP-2568) Downcase class name before validating

Previously the check for a valid name was done against the raw input,
however it later downcased the name and used that form. This order
caused Class['A'] to be an error, which isn't desired (at least not
until PUP-1810 is taken care of). By just changing the order of
operations capital letters are once again allowed.
Merge pull request #2626 from kbarber/ticket/stable/pup-2508-no-environment-trn-uuid-compilation-failure

(PUP-2508) Ensure env & trn-uuid are sent when configurer failures occur