Adds documentation about upgrading to 1.0.0

Author: errm

README.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-**systemd** input plugin reads logs from the systemd journal  
+**systemd** input plugin reads logs from the systemd journal
 **systemd** filter plugin allows for basic manipulation of systemd journal entries
 
 ## Support
@@ -35,6 +35,10 @@ or
 
     td-agent-gem install fluent-plugin-systemd -v 0.3.1
 
+## Upgrading
+
+If you are upgrading to version 1.0 from a previous version of this plugin take a look at the [upgrade documentation](docs/upgrading.md). A number of deprecated config options were removed so you might need to update your configuration.
+
 ## Input Plugin Configuration
 
     <source>
@@ -76,34 +80,15 @@ reading all logs from the journal.
 See [matching details](docs/Matching-Details.md) for a more exhaustive
 description of this property and how to use it.
 
-**`pos_file`**
-
-_This parameter is deprecated and will be removed in favour of storage in v1.0._
-
-
-Path to pos file, stores the journald cursor. File is created if does not exist.
-
 **`storage`**
 
 Configuration for a [storage plugin](http://docs.fluentd.org/v0.14/articles/storage-plugin-overview) used to store the journald cursor.
 
-_Upgrading from `pos_file`_
-
-If `pos_file` is specified in addition to a storage plugin with persistent set to true, the cursor will be
-copied from the `pos_file` on startup, and the old `pos_file` removed.
-
 **`read_from_head`**
 
 If true reads all available journal from head, otherwise starts reading from tail,
  ignored if pos file exists (and is valid). Defaults to false.
 
-**`strip_underscores`**
-
-_This parameter is deprecated and will be removed in favour of entry in v1.0._
-
-If true strips underscores from the beginning of systemd field names.
-May be useful if outputting to kibana, as underscore prefixed fields are unindexed there.
-
 **`entry`**
 
 Optional configuration for an embeded systemd entry filter. See the  [Filter Plugin Configuration](#filter-plugin-configuration) for config reference.

docs/upgrading.md

@@ -0,0 +1,52 @@
+# Upgrading
+
+## To Version 1.0
+
+Version 1.0 removes a number of configuration options that had been deprecated by previous versions of the plugin. This was done to reduce the size of the code base and make maintenance simpler.
+
+If you have been paying attention to (and fixing) the deprecation warnings introduced by previous versions of the plugin then there is nothing for you to do. If you have not already done so it is recommended to first upgrade to version `0.3.1` and fix any warnings before trying version `1.0.0` or above.
+
+Version 1.0 of fluent-plugin-systemd only supports fluentd 0.14.11 and above (including fluentd 1.0+), if you are using tdagent you need to be using version 3 or above.
+
+### `pos_file`
+
+Previous versions of the plugin used the `pos_file` config value to specify a file that the position or cursor from the systemd journal would be written to. This was replaced by a generic fluentd storage block that allows much more flexibility in how the cursor is persisted. Take a look at the [fluentd documentation](https://docs.fluentd.org/v1.0/articles/storage-section) to find out more about this.
+
+Before you upgrade to 1.0 you should migrate `pos_file` to a storage block.
+
+```
+pos_file /var/log/journald.pos
+```
+
+could be rewritten as
+
+```
+<storage>
+  @type local
+  persistent true
+  path /var/log/journald_pos.json
+</storage>
+```
+
+If you want to update this configuration without skipping any entries if you supply the `pos_file` and a storage block at the same time version `0.3.1` will copy the cursor from the path given in `pos_file` to the given storage.
+
+### `strip_underscores`
+
+The legacy `strip_underscores` method is removed in version `1.0.0` and above. The same functionality can be achieved by setting the `fields_strip_underscores` on an entry block. The entry block allows many more options for mutating journal entries.
+
+```
+strip_underscores true
+```
+
+should be rewritten as
+
+```
+<entry>
+  fields_strip_underscores true
+</entry>
+```
+
+### `filters`
+
+In version 1.0.0 the `filters` parameter was renamed as `matches` in order to more closely align the plugin with the names used in the systemd documentation. `filters` is deprecated and will be removed in a future version. Other than renaming the parameter no changes have been made to it's structure or operation.
+