(MODULES-7840) Update docs with better parameter descriptions

The windows provider only runs bare commands, which means an embedded pipe
will be seen as a command parameter and not a pipe. This change adds a cmd
shell as the primary command such that piping, etc. will work as expected.

Adds an acceptance directory containing a set of scaffold test files
and helpers to allow for testing this module with beaker-puppet instead
of beaker-puppet_install_helper (which is no longer supported). The
README in the acceptance directory describes how to run the new tests.

This leaves the existing tests in spec/acceptance intact for now; in the
future these old tests will either be migrated to the acceptance
directory, or (if they test puppet 3 functionality) removed.

Take note that this process will also eventually remove beaker-rspec,
since it is incompatible with the use of subcommands in beaker 4.

…-acceptance

(MODULES-8348) Acceptance scaffold with beaker-puppet

…ss-check-for-inherited-permissions

(MODULES-8406) fix the broken unless check for inherited permissions

Packages from the puppet6 collections (and moving forward from that) we no
longer carry the mcollective service. So for upgrades to collections other
than puppet5 and PC1 we should ignore the mcollective service.

This commit updates the service logic to use a new $_service_names parameter
that is updated to exclude mcollective with anything that is not collections
puppet5 or PC1

(MODULES-8319) Update service to exclude MCO for puppet > 6

The puppet_agent module no longer supports upgrades from Puppet 3 nodes.
This commit removes the remaining Puppet 3 code from the main manifests
and any remaining spec tests.

An undefined aio_agent_version fact means we're running on a pre-Puppet
4 node. Since pre-Puppet 4 upgrades are no longer supported, we should
fail the run if aio_agent_version is undefined.

(MODULES-8523) Remove legacy Puppet 3 code

(MODULES-8348) Refactor the acceptance test scaffold

(maint) Update minimum acceptance beaker-puppet version

Since the MSI installer already preserves the environment of an existing
agent install, there's no need to specify it. Additionally, when there is
no 'environment' key present in puppet.conf, this would set the environment
key to the default value 'production', which can cause nodes to be
incorrectly classified after upgrades.

(MODULES-8432) refresh PA repo if the version is not in the local cache

(MODULES-4730) Do not pass the agent environment during MSI installs

We no longer ship these platforms in the latest 5.5.x stream.

(MODULES-8320) Remove old platforms

This commit updates the install_shell task implementation to use https endpoints when downloading puppet-agent packages. Previously the http endpoints were used.

(PE-25542) add RHEL8 to puppet agent module

(FM-7732) Download puppet-agent packages over https

Currently, the update testing in the acceptance directory does not
test by waiting for pidfiles during installations. For
MacOS/Solaris/Windows this means the acceptance tests will not work,
since those platforms will spawn scripts to perform installations
outside of an agent run

So this commit updates the acceptance testing to include waiting for
pidfiles after the puppet run completes so the testing will wait for
the full installation.

There were a few larger refactors done to help facilitate the changes:

1. new functions for waiting for puppet to finish and waiting on
installation PIDs

2. the actual execution of puppet to perform the upgrade now consists
of turning on the puppet service rather than executing 'puppet agent
-t'. This is the approach we use when testing upgrades in PE and
should be consistent

3. several functions were refactored to be smaller and more focused.

MacOS/Solaris/Windows

(MODULES-5535) Update test matrix to work with MacOS/Solaris/Windows

The zypper provider doesn't support purge

Allows SLES upgrades to use publicly available packages instead of
packages from the PE master while upgrading puppet-agent. This enables
upgrades for SLES users using open source Puppet.

…rades

(MODULES-8598) Enable SLES upgrades outside of Puppet Enterprise

This adds documentation to help developers get started using this repo.
This moves some existing documentation out of CONTRIBUTING.md and into
a new DEVELOPERS.md. A few key features of this new file are:

- Tools for iterative development, i.e. ways to quickly make and test
  changes to the module
- Which files to read to better understand a repo
- Other tools to ease development, e.g. Jenkins pipelines to run

This commit decreases the feedback cycle time to enable iterative
development. The gist is that a developer can use Docker to test
out upgrades on a machine.

The `docker/bin/upgrade.sh [<PLATFORM>] [<BEFORE>] [<AFTER>]`
command builds a container on the `<PLATFORM>` platform that has
the `<BEFORE>` version of puppet on it and adds the `puppet_agent`
module. It then runs `puppet apply` in the container such that the
`<AFTER>` version of puppet exists afterward. This script ends with
a shell inside the container.

Available platforms are Ubuntu Xenial (`ubuntu`) and CentOS 7
(`centos`).

Also available is `docker/bin/versions.sh [<PLATFORMS>]`, which
will output which versions of puppet are available on given
comma-separated `<PLATFORMS>`.

For full details, see docker/ubuntu/Dockerfile or
docker/centos/Dockerfile.

(PA-2282) Add Docker workflow for iterative development

- Correct server version restriction in puppet5 -> puppet6 upgrade test
- A few readability edits for comments and logging

Several puppet.conf settings were deprecated in puppet 5:
- app_management
- ignorecache
- configtimeout
- trusted_server_facts

This removes those settings while performing any upgrade to a version of
puppet 5 or greater.

$logdir appears to have been in use for mcollective, which is not
managed as part of this module. This commit removed the unnecessary
logdir param

This commit performs a major refactor of the structure of identifying
and using sources for the packages to upgrade. Before this commit,
sources were identified in a myriad of different ways with no
consistency.

All source identification now happens as the first action in the
osfamily manifests. Sources are identified in these manifests and
then used to pull packages sources (if necessary) or identify where
the osfamily manifest downloads repos.

Parts of the init manifest that were previously calculating things
like package name have been moved to the osfamily manifests as well.

MacOS installations now work, FOSS or PE,
using puppet_agent::prepare::package and the new
puppet_agent::prepare::package_source class. This commit removes
the checks for PE and MacOS version from the Darwin class so MacOS
upgrades are available in FOSS land.

Previously, solaris and MacOS install scripts would create pidfiles
in temp directories to identify an install was running to other
installers. This commit moves the pidfiles to the puppet statedir.

(MODULES-8599) Refactor sources and enable Darwin FOSS installs

(PA-2282) Add developer documentation

Various improvments to include details related to newer Puppet package
repos and other minor clarifications.

Removed a reference about upgrading to Puppet 4, which is no longer
supported - Puppet 4 is the baseline version you can use this module to
upgrade from.

Previously, the tests were omitting the `params` argument to `run_task`.
In newer versions of BoltSpec, that parameter is going to be required,
so now we always pass it.

SLES 15 uses gpg 2.2, which changed some of its key output formatting
and is noisier about missing commands. This change normalizes the text
parsing of gpg keys, using the --with-colons option, that is recommended
in the man page for use in scripts. The updated parsing pipelines work with
older and newer versions of gpg.