(maint) formatting
Update CONTRIBUTING.md

Added link to mailing list so that people can find it.
tests: add environment variable handling facilities

1) Execute-WithEnvironmentBackup - to be able to freely manipulate the
environment during tests. Exception-safe.
2) Add-EnvironmentVariable - set the variable at given scope, making
sure to update it also at Process scope if necessary
3) Remove-EnvironmentVariable - remove from all scopes
4) Add-DirectoryToPath - add to path at given scope, making sure to update
the path also at Process scope
5) Remove-DirectoryFromPath - remove it from path at all scopes
6) Assert-OnPath, Assert-NotOnPath - verify the directory is or is not
present on path at given scope
add tests for Chocolatey setup (Initialize-Chocolatey)

Note: the tests currently assume the test suite is run with administrative
rights (i.e. elevated) with UAC enabled.

Unfortunately, it is not possible to test the most common scenario, i.e.
first installation on a clean machine with no existing environment
variables or arguments to the installer, without making specific
assumptions about the test machine. (If the tests did that, the primary
Chocolatey installation on the developer machine could get overwritten.)

The default installation tests will thus only be performed if no existing
Chocolatey installation is detected in the default install location.
setup tests: conditionally test default installation

Default installation (no arguments or preexisting environment variables)
can be tested only when the test machine does not already have Chocolatey
installed in the default location (otherwise it would get overwritten).

To enable these tests, make sure your Chocolatey is installed in a custom
location.
setup tests: mock UAC status

This allows testing setup behavior both with UAC enabled and disabled.

The "mocking" mechanism actually changes the UAC registry setting, which
is read by UAC checking code in Chocolatey. Since the change requires OS
restart to take effect, it is indeed a mockup. However, the test suite
should not be interrupted, so that the setting is changed back to the
original value.

No effort has been made to support running the tests on XP. A modern OS is
assumed.
add Test-AdminRights helper

This helper tests whether the current user identity is a member of the
Administrators group, i.e. if the current process has administrator
rights.

On systems with UAC enabled, this helper returns true only if the current
process is running elevated (so it actually has admin rights).

All existing admin checks in Chocolatey code are refactored to take
advantage of this helper.
Test-AdminRights: request WindowsIdentity with minimal access necessary

To check group membership, only TOKEN_QUERY is needed ([1]).
The token, however, needs to be an impersonation token, so in certain
circumstances TOKEN_DUPLICATE is also needed ([2]).

Requesting the WindowsIdentity with minimum access level is slightly
better from a security standpoint.

[1] CheckTokenMembership:
http://msdn.microsoft.com/en-us/library/windows/desktop/aa376389.aspx

[2] WindowsPrincipal source, bool IsInRole (SecurityIdentifier sid):
http://referencesource.microsoft.com/#mscorlib/system/security/principal/windowsprincipal.cs
enable mocking Test-AdminRights for setup tests

As Chocolatey setup code explicitly imports the helpers module, Pester
mocking mechanisms do not work (the mocks are overridden when the helpers
are imported again).

Mocking the admin rights check in setup tests is critical to making it
possible to test Chocolatey setup at various user right levels.

For setup tests, substitute Test-AdminRights implementation in the
installation package with a stub returning a canned answer.

This slightly reduces the accuracy of setup tests, as not 100% of
production code is tested, but keeping production code pure is more
important.

As an added benefit, this is the first step in enabling the tests to be
run as a standard user.
setup tests: add simulated standard user scenarios

With the facility of mocking admin rights tests in place, it is now
possible to test setup behavior for limited users (and un-elevated admins).
setup tests: with admin rights, variables should be set at Machine level regardless of UAC

Provided the process is running elevated (i.e. with admin rights),
Chocolatey should always be set up at machine (all users) level.
There is no need to punish security-conscious users who run their systems
with UAC enabled.
when running with administrative rights, set environment variables at Machine scope

The CurrentPrincipal::IsInRole(Administrators) check is sufficient to
ascertain administrative rights, whether UAC is enabled or not.

In particular, if UAC is enabled, this check will only return true if
running elevated.

This change enables per-machine installation on systems with UAC enabled
(only if the user installs/invokes Chocolatey from an elevated shell, so UAC
prompt is not triggered), while not disrupting the behavior for standard users.
setup tests: do not vary by UAC status

Since UAC status is no longer a factor influencing setup behavior, remove
effectively duplicated tests.

Tampering with UAC settings is also no longer necessary, which eliminates
the threat of interrupted tests leaving the OS with changed UAC status.
setup tests: fix formatting

Separated from the previous commit so that the previous diff is easier to
review.
rename Test-AdminRights to Test-ProcessAdminRights

As per @ferventcoder's suggestion. Longer name, but makes it more explicit
the current process rights are tested (in contrast to e.g. the user
account being member of the Administrators group).
helpers: add environment variable management abstractions

The three added functions wrap [Environment]::Get/SetEnvironmentVariable
and obtaining variable names from the registry. The purpose is to enable
mocking environment manipulation in tests.

The functions are exported from the module, otherwise core Chocolatey
(Chocolatey-Python, Chocolatey-RubyGem) would not be able to use them.
Nevertheless, packages should in most circumstances use the high-level
Install-ChocolateyEnvironmentVariable and Install-ChocolateyPath helpers.

All Chocolatey code is changed to use these new functions.
tests: add environment manipulation mocking facility

Add implementations of environment manipulation functions that operate on
an object stored in a global variable, instead of on the live system
environment.

All test code that might manipulate the environment should be wrapped in a
call to Execute-WithEnvironmentProtection. This function takes a snapshot
of the environment, initializes the mocked environment state based on that
snapshot, executes test code and reverts any modifications to the
environment to the state from the snapshot.

Reverting environment changes is important for two reasons:
1) although the mocking mechanism prevents changes to the actual Machine
and User environment (by cooperating code), Process environment still
needs to be restored.
2) there is the possibility that some un-cooperating code will execute
that will, by bug or omission, bypass the environment management functions
and modify the live environment. The environment restoring code will
mitigate the damage and will emit a warning in such case, so that the
culprit may be caught.

If a test case tries to alter the environment without using the
mocking/protection facility, an error will occur, instructing to use the
appropriate construct in the test case.

Together with mocking admin rights tests implemented earlier, this commit
makes it possible to run Chocolatey setup and Update-SessionEnvironment
tests as standard user, with no fear of corrupting systemwide state.

Implementation note: diagnostic messages are emitted at Verbose level,
because Debug failed to appear during setup tests (no time to investigate).
Merge branch 'per-machine-install-v6' into stable

* per-machine-install-v6:
  tests: add environment manipulation mocking facility
  helpers: add environment variable management abstractions
  rename Test-AdminRights to Test-ProcessAdminRights
  setup tests: fix formatting
  setup tests: do not vary by UAC status
  when running with administrative rights, set environment variables at Machine scope
  setup tests: with admin rights, variables should be set at Machine level regardless of UAC
  setup tests: add simulated standard user scenarios
  enable mocking Test-AdminRights for setup tests
  Test-AdminRights: request WindowsIdentity with minimal access necessary
  add Test-AdminRights helper
  setup tests: mock UAC status
  setup tests: conditionally test default installation
  add tests for Chocolatey setup (Initialize-Chocolatey)
  tests: add environment variable handling facilities
(GH-426) Log Error output

This ensures we log error output instead of trying to shove it into a package
list, which is not a good idea. Instead we will log it but not throw an error
since nuget tends to error for no apparent reason sometimes.
Merge branch 'stable'

* stable:
  (GH-426) Log Error output
  tests: add environment manipulation mocking facility
  helpers: add environment variable management abstractions
  rename Test-AdminRights to Test-ProcessAdminRights
  setup tests: fix formatting
  setup tests: do not vary by UAC status
  when running with administrative rights, set environment variables at Machine scope
  setup tests: with admin rights, variables should be set at Machine level regardless of UAC
  setup tests: add simulated standard user scenarios
  enable mocking Test-AdminRights for setup tests
  Test-AdminRights: request WindowsIdentity with minimal access necessary
  add Test-AdminRights helper
  setup tests: mock UAC status
  setup tests: conditionally test default installation
  add tests for Chocolatey setup (Initialize-Chocolatey)
  tests: add environment variable handling facilities
  (maint) formatting