add README section on API deprecations since version 1.0.0

README.md

@@ -11,6 +11,7 @@
     * [Setup requirements](#setup-requirements)
     * [Beginning with concat](#beginning-with-concat)
 4. [Usage - Configuration options and additional functionality](#usage)
+    * [API _deprecations_](#api-deprecations)
 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)
@@ -55,6 +56,9 @@ concat::fragment { 'tmpfile':
 
 ##Usage
 
+Please be aware that there have been a number of [API
+_deprecations_](#api-deprecations).
+
 If you wanted a /etc/motd file that listed all the major modules
 on the machine.  And that would be maintained automatically even
 if you just remove the include lines for other modules you could
@@ -275,6 +279,137 @@ Control the filebucket behavior for the fragment.
 ######Example
 - backup => 'puppet'
 
+### API _deprecations_
+
+#### Since version `1.0.0`
+
+##### `concat{}` `warn` parameter
+
+```puppet
+concat { '/tmp/file':
+  ensure => present,
+  warn   => 'true',  # generates stringified boolean value warning
+}
+```
+
+Using stringified Boolean values as the `warn` parameter to `concat` is
+deprecated, generates a catalog compile time warning, and will be silently
+treated as the concatenated file header/warning message in a future release.
+
+The following strings are considered a stringified Boolean value:
+
+ * `'true'`
+ * `'yes'`
+ * `'on'`
+ * `'false'`
+ * `'no'`
+ * `'off'`
+
+Please migrate to using the Puppet DSL's native [Boolean data
+type](http://docs.puppetlabs.com/puppet/3/reference/lang_datatypes.html#booleans).
+
+##### `concat{}` `gnu` parameter
+
+```puppet
+concat { '/tmp/file':
+  ensure => present,
+  gnu    => $foo,    # generates deprecation warning
+}
+```
+
+The `gnu` parameter to `concat` is deprecated, generates a catalog compile time
+warning, and has no effect.  This parameter will be removed in a future
+release.
+
+Note that this parameter was silently ignored in the `1.0.0` release.
+
+##### `concat::fragment{}` `ensure` parameter
+
+```puppet
+concat::fragment { 'cpuinfo':
+  ensure => '/proc/cpuinfo', # generates deprecation warning
+  target => '/tmp/file',
+}
+```
+
+Passing a value other than `'present'` or `'absent'` as the `ensure` parameter
+to `concat::fragment` is deprecated and generates a catalog compile time
+warning.  The warning will become a catalog compilation failure in a future
+release.
+
+This type emulates the Puppet core `file` type's disfavored [`ensure`
+semantics](http://docs.puppetlabs.com/references/latest/type.html#file-attribute-ensure)
+of treating a file path as a directive to create a symlink.  This feature is
+problematic in several ways.  It copies an API semantic of another type that is
+both frowned upon and not generally well known.  It's behavior may be
+surprising in that the target concatenated file will not be a symlink nor is
+there any common file system that has a concept of a section of a plain file
+being symbolically linked to another file.  Additionally, the behavior is
+generally inconsistent with most Puppet types in that a missing source file
+will be silently ignored.
+
+If you want to use the content of a file as a fragment please use the `source`
+parameter.
+
+##### `concat::fragment{}` `mode/owner/group` parameters
+
+```puppet
+concat::fragment { 'foo':
+  target  => '/tmp/file',
+  content => 'foo',
+  mode    => $mode,       # generates deprecation warning
+  owner   => $owner,      # generates deprecation warning
+  group   => $group,      # generates deprecation warning
+}
+```
+
+The `mode` parameter to `concat::fragment` is deprecated, generates a catalog compile time warning, and has no effect.
+
+The `owner` parameter to `concat::fragment` is deprecated, generates a catalog
+compile time warning, and has no effect.
+
+The `group` parameter to `concat::fragment` is deprecated, generates a catalog
+compile time warning, and has no effect.
+
+These parameters had no user visible effect in version `1.0.0` and will be
+removed in a future release.
+
+##### `concat::fragment{}` `backup` parameter
+
+```puppet
+concat::fragment { 'foo':
+  target  => '/tmp/file',
+  content => 'foo',
+  backup  => 'bar',       # generates deprecation warning
+}
+```
+
+The `backup` parameter to `concat::fragment` is deprecated, generates a catalog
+compile time warning, and has no effect.  It will be removed in a future
+release.
+
+In the `1.0.0` release this parameter controlled file bucketing of the file
+fragment.  Bucketting the fragment(s) is redundant with bucketting the final
+concatenated file and this feature has been removed.
+
+##### `class { 'concat::setup': }`
+
+```puppet
+include concat::setup     # generates deprecation warning
+
+class { 'concat::setup: } # generates deprecation warning
+```
+
+The `concat::setup` class is deprecated as a public API of this module and
+should no longer be directly included in the manifest.  This class may be
+removed in a future release.
+
+##### Parameter validation
+
+While not an API depreciation, users should be aware that all public parameters
+in this module are now validated for at least variable type.  This may cause
+validation errors in a manifest that was previously silently misbehaving.
+
 ##Limitations
 
 This module has been tested on: