Merge pull request #193 from bastelfreak/deprecate

Deprecate symbolized facts

Author: bastelfreak

README.md

@@ -22,7 +22,7 @@ If you're using Bundler to manage gems in your module repository, install `rspec
 1. Add the following line to your `Gemfile`:
 
 ```ruby
-gem 'rspec-puppet-facts', :require => false
+gem 'rspec-puppet-facts', require: false
 ```
 
 2. Run `bundle install`.
@@ -54,38 +54,18 @@ By default, `rspec-puppet-facts` provides the facts only for `x86_64` architectu
     * `'operatingsystem'`        - The name of the operating system, as a string.
     * `'operatingsystemrelease'` - An array of version numbers, as strings.
 
-This is particularly useful if your module is split into operating system subclasses. For example, if you had a class called `myclass::debian` that you wanted to test against Debian 6 and Debian 7 on both `x86_64` _and_ `i386` architectures, you could write the following test:
+This is particularly useful if your module is split into operating system subclasses. For example, if you had a class called `myclass::debian` that you wanted to test against Debian 12 and Debian 11 on both `x86_64` _and_ `i386` architectures, you could write the following test:
 
 ```ruby
 require 'spec_helper'
 
-describe 'myclass::debian' do
-  test_on = {
-    :hardwaremodels => ['x86_64', 'i386'],
-    :supported_os   => [
-      {
-        'operatingsystem'        => 'Debian',
-        'operatingsystemrelease' => ['6', '7'],
-      },
-    ],
-  }
-
-  on_supported_os(test_on).each do |os, os_facts|
-    let (:facts) { os_facts }
-    it { is_expected.to compile.with_all_deps }
-  end
-end
-```
-Ruby 1.9 and later:
-```ruby
-require 'spec_helper'
-
 describe 'myclass::raspbian' do
   test_on = {
+    hardwaremodels: ['x86_64', 'i386'],
     supported_os: [
       {
         'operatingsystem'        => 'Debian',
-        'operatingsystemrelease' => ['10', '9', '8'],
+        'operatingsystemrelease' => ['12', '11'],
       },
     ],
   }
@@ -98,17 +78,64 @@ end
 
 ## Specifying a default Facter version
 
-By default, `on_supported_os` will return the facts for the version of Facter
-that it has loaded (usually this is Facter 2.5.1). This behaviour can be
-overridden by setting the `default_facter_version` RSpec setting in your
-`spec/spec_helper.rb` file.
+By default, `on_supported_os` will return the facts for the version of Facter that it has loaded. It will check for the loaded Puppet version and maps that to the Facter version that Perforce released in the matching AIO.
+The mapping is stored in `ext/puppet_agent_components.json` (check the [maintenance](#maintenance) section for details) and computated in the `facter_version_for_puppet_version` method.
+This behaviour can be overridden by setting the `default_facter_version` RSpec setting in your `spec/spec_helper.rb` file.
 
 ```ruby
 RSpec.configure do |c|
   c.default_facter_version = '3.14.0'
 end
 ```
 
+## Symbolized vs stringified facts
+
+For a long long time, the first level of keys in a factsets were symbols.
+This was fine before there were structured facts, but structured facts ended up as nested hashes that always had strings.
+This doesn't make sense and easy to get wrong.
+The original data contains only strings so conversion actually costs performance.
+
+The option to switch between symbolized vs stringified facts was introduced in [25634f4481f20f2fc7444e867928ca607234e33e](https://github.com/voxpupuli/rspec-puppet-facts/commit/25634f4481f20f2fc7444e867928ca607234e33e) (Release [1.9.5](https://github.com/voxpupuli/rspec-puppet-facts/blob/master/CHANGELOG.md#2019-07-29---release-195)), but version 5.0.0 has resolved various implementation bugs.
+
+This can be configured like this:
+
+```ruby
+RSpec.configure do |c|
+  c.facterdb_string_keys = false
+end
+```
+
+In the 5.x release series of rspec-puppet-facts the default `false` is deprecated.
+With the 6.0.0 release we will flip it to `true` (https://github.com/voxpupuli/rspec-puppet-facts/pull/189).
+
+You may have the following rspec-puppet test using deprecated symbolized facts:
+
+```ruby
+on_supported_os.each do |os, os_facts|
+  case os_facts[:os]['name']
+  when 'Archlinux'
+    context 'on Archlinux' do
+      it { is_expected.to contain_package('borg') }
+    end
+  when 'Ubuntu'
+  end
+end
+```
+
+With the string facts, the same test looks like:
+
+```ruby
+on_supported_os.each do |os, os_facts|
+  case os_facts['os']['name']
+  when 'Archlinux'
+    context 'on Archlinux' do
+      it { is_expected.to contain_package('borg') }
+    end
+  when 'Ubuntu'
+  end
+end
+```
+
 ## Usage
 
 Use the `on_supported_os` iterator to loop through all of your module's supported operating systems. This allows you to simplify your tests and remove a lot of duplicate code.
@@ -475,7 +502,7 @@ fact sets that only make sense in your environment or might contain sensitive in
 To supply external facts to facterdb just set the `FACTERDB_SEARCH_PATHS` environment variable with one or more
 paths to your facts.
 
-When separating paths please use the default path separator character supported by your OS.  
+When separating paths please use the default path separator character supported by your OS.
 * Unix/Linux/OSX = `:`
 * Windows = `;`