Merge pull request #54 from Lightning-/great_rework

great rework

.fixtures.yml

@@ -2,4 +2,3 @@ fixtures:
   repositories:
     powershell:  'https://github.com/puppetlabs/puppetlabs-powershell.git'
     pwshlib: 'https://github.com/puppetlabs/ruby-pwsh.git'
-    win_facts:  'https://github.com/liamjbennett/puppet-win_facts.git'

LICENSE

@@ -188,6 +188,7 @@
       identification within third-party archives.
 
    Copyright 2014 Liam Bennett ([email protected])
+   Copyright 2023 markt.de GmbH & Co. KG
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,187 +1,42 @@
 # puppet-windows_power
 
-#### Table of Contents
+## Module description
 
-1. [Overview](#overview)
-2. [Module Description - What is the windows_power module?](#module-description)
-3. [Setup - The basics of getting started with windows_power](#setup)
-    * [What windows_power affects](#what-power-affects)
-    * [Setup requirements](#setup-requirements)
-    * [Beginning with windows_power](#beginning-with-power)
-4. [Usage - Configuration options and additional functionality](#usage)
-5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
-5. [Limitations - OS compatibility, etc.](#limitations)
-6. [Development - Guide for contributing to the module](#development)
+Puppet module for managing Windows hibernation settings, power schemes and power devices (or power request overrides respectively).
 
-## Overview
+## Setup, Usage, Reference
 
-Puppet module for managing windows power settings
+Summary:
+- use class `windows_power` to manage Windows power devices (physical, logical and virtual); this wraps the defined type `windows_power::device`
+- use class `windows_power::hibernate` to manage Windows hibernate settings
+- use class `windows_power::scheme` to manage Windows power scheme
+- shipped fact `power_devices` contains all kind of system's power devices, their various wakeup capabilities and their power request overrides
+- shipped fact `power_schemes` contains the system's power schemes and their activation state
 
-[![Build Status](https://travis-ci.org/voxpupuli/puppet-windows_power.svg?branch=master)](https://travis-ci.org/voxpupuli/puppet-windows_power)
-## Module Description
+See [REFERENCE.md](REFERENCE.md) for further details and practical examples.
 
-The purpose of this module is to manage each of the windows power schemes and the various global power settings
+## Special notice for v4.0.0
 
-## Setup
+Version 4.0.0 is a complete rewrite and modernization of the previous module and breaks with configuration compatibility.
 
-### What windows_power affects
+It also drops support for legacy Windows systems and removes functionality targeting those legacy systems. If you have any of those systems in place (such as Windows XP or Windows Server 2008) don't update.
 
-* Creates new power schemes (which will alter registry settings)
-
-### Beginning with windows_power
-
-Create new power scheme:
-
-```puppet
-windows_power::schemes::scheme { 'test scheme':
-  scheme_name     => 'test',
-  scheme_guid     => '381b4222-f694-41f0-9685-ff5bbxx65ddx',
-  template_scheme => '381b4222-f694-41f0-9685-ff5bb260df2e',
-  activation      => 'active',
-  ensure          => 'present',
-}
-```
-
-Set monitor timeout in 'Balanced' power scheme to 10 minutes:
-
-```puppet
-windows_power::schemes::settings { 'set monitor timeout':
-  scheme_name => 'SCHEME_BALANCED',
-  setting     => 'monitor-timeout-ac',
-  value       => '10',
-}
-
-```
-
-## Usage
-
-### Classes and Defined Types:
-
-#### Defined Type: `windows_power::schemes::scheme`
-
-**Parameters within `windows_power::schemes::scheme`:**
-
-##### `scheme_name`
-
-The name of the scheme to configure
-
-##### `scheme_guid`
-
-The windows guid used to uniquely identify the power scheme
-
-##### `template_scheme`
-
-The windows guid of an existing scheme to be used as a template for the current scheme
-
-##### `activation`
-
-Set the current scheme as the active scheme
-
-##### `ensure`
-
-Configure if the scheme is present or absent
-The initial version
-
-#### Defined Type: `windows_power::schemes::settings`
-
-**Parameters within `windows_power::schemes::settings`:**
-
-##### `scheme_name`
-
-The name of the scheme to configure
-
-##### `setting`
-
-The setting to configure
-
-##### `value`
-
-The value set the setting to - minutes or throttle
-
-#### Defined Type: `windows_power::global::battery`
-
-**Parameters within `windows_power::global::battery`:**
-
-##### `setting`
-
-Battery alarm setting to The initial versionconfigure
-
-##### `status`
-
-Setting configuration (on/off) or percentage (in the case of the level setting)
-
-##### `criticality`
-
-The level of battery criticality at which to provide an alarm. LOW or HIGH.
-
-#### Defined Type: `windows_power::global::flags`
-
-**Parameters within `windows_power::global::flags`:**
-
-##### `setting`
-
-The global power flag to configure
-
-##### `status`
-
-Setting configuration (on/off)
-
-#### Defined Type: `windows_power::global::hiberation`
-
-**Parameters within `windows_power::global::hibernation`:**
-
-##### `status`
-
-Setting configuration (on/off)
-
-#### Defined Type: `windows_power::devices::override`
-
-**Parameters within `windows_power::devices::override`:**
-
-##### `type`
-
-Specifies one of the following caller types: PROCESS, SERVICE, DRIVER
-
-##### `request`
-
-Specifies one or more of the following Power Request Types: Display, System, Awaymode
-
-#### Defined Type: `windows_power::devices::wake`
-
-**Parameters within `windows_power::devices::wake`:**
-
-##### `device`
-
-Specifies the device name
-
-##### `ensure`
-
-Enable or disable the device for waking
-
-## Reference
-
-### Defined Types:
+## Limitations
 
-#### Public Defined Types:
+Due to the nature of Windows' way to configure things, we can't just write a config file with desired settings and tell Windows to apply that (or something similar). As well we're not able to determine the current state of some settings (e.g. the timeouts in a power scheme) at all.
 
-* [`windows_power::schemes::scheme`](#define-schemes-scheme): Guides the management of windows power schemes
-* [`windows_power::schemes::settings`](#define-schemes-settings): Configures individual settings with a given scheme.
-* [`windows_power::global::battery`](#define-global-battery): Configure power battery alarms.
-* [`windows_power::global::flags`](#define-global-flags): Configure the global settings for windows power schemes
-* [`windows_power::global::hiberation`](#define-global-hibernation): Configure the hibernation setting
-* [`windows_power::devices::override`](#define-devices-override): Configure power overrides for certain devices
-* [`windows_power::devices::wake`](#define-devices-wake): Configure the device wake settings
+Therefore, some commands are applied with every Puppet run to ensure the desired state. Additionally, it might need more than one Puppet run to achieve the final state.
 
-## Limitations
+We know that this is very bad Puppet style and we did our best to keep this as minimal as possible. As well we put a lot of effort into making the module fail-safe (e.g. not configuring the wrong power scheme if a new one was created but hasn't been successfully activated yet) at the cost of "might need more than one run".
 
-This module is tested on the following platforms:
+This module assumes that your system is not managed by an Active Directory controller. We have no way of testing what happens if your system (or parts of it including the power management) is controlled this way and you should use the AD's capabilities of managing power-things then anyways.
 
-* Windows 2008 R2
+Also note that device names, scheme names and similar are subjected to localization (whyever ...). This means that you will have a device `System timer` on an English system and a `Systemzeitgeber` on a German system for example. Configuring devices and overrides in an environment with mixed installation languages is probably quite annoying as you will have to create different profiles for different languages with the corresponding device names.
 
-It is tested with the OSS version of Puppet only.
+If you have any ideas, suggestions, improvements ... please get in touch with us.
 
 ## Development
 
-### Contributing
+Development happens on GitHub in the well known way (fork, PR, issue, etc.).
 
-Please read CONTRIBUTING.md for full details on contributing to this project.
+Please feel free to report problems, suggest improvements, drop new ideas or teach us how to handle things better.