receiving side: placeholder as simple on|off property

docs/changelog.rst

@@ -3,6 +3,7 @@
 .. |bugfix| replace:: [BUG]
 .. |docs| replace:: [DOCS]
 .. |feature| replace:: [FEATURE]
+.. |mig| replace:: **[MIGRATION]**
 
 .. _changelog:
 
@@ -19,6 +20,7 @@ We use the following annotations for classifying changes:
 * |break| Change that breaks interoperability or persistent state representation with previous releases.
   As a package maintainer, make sure to warn your users about config breakage somehow.
   Note that even updating the package on both sides might not be sufficient, e.g. if persistent state needs to be migrated to a new format.
+* |mig| Migration that must be run by the user.
 * |feature| Change that introduces new functionality.
 * |bugfix| Change that fixes a bug, no regressions or incompatibilities expected.
 * |docs| Change to the documentation.
@@ -40,6 +42,7 @@ It breaks both configuration and transport format, and thus requires manual inte
 Notes to Package Maintainers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+* Notify users about migrations (see changes attributed with |mig| below)
 * If the daemon crashes, the stack trace produced by the Go runtime and possibly diagnostic output of zrepl will be written to stderr.
   This behavior is independent from the ``stdout`` outlet type.
   Please make sure the stderr output of the daemon is captured somewhere.
@@ -52,6 +55,15 @@ Notes to Package Maintainers
 Changes
 ~~~~~~~
 
+* |break| |mig| Placeholder property representation changed
+
+  * The :ref:`placeholder property <replication-placeholder-property>` now uses ``on|off`` as values
+    instead of hashes of the dataset path. This permits renames of the sink filesystem without
+    updating all placeholder properties.
+  * Relevant for 0.0.X-0.1-rc* to 0.1 migrations
+  * Make sure your config is valid with ``zrepl configcheck``
+  * Run ``zrepl migrate 0.0.X:0.1:placeholder``
+
 * |feature| :issue:`55` : Push replication (see :ref:`push job <job-push>` and :ref:`sink job <job-sink>`)
 * |feature| :ref:`TCP Transport <transport-tcp>`
 * |feature| :ref:`TCP + TLS client authentication transport <transport-tcp+tlsclientauth>`

docs/configuration/jobs.rst

@@ -109,7 +109,9 @@ It is a bookmark of the most recent successfully replicated snapshot to the rece
 It is is used by the :ref:`not_replicated <prune-keep-not-replicated>` keep rule to identify all snapshots that have not yet been replicated to the receiving side.
 Regardless of whether that keep rule is used, the bookmark ensures that replication can always continue incrementally.
 
-**Placeholder filesystems** on the receiving side are regular ZFS filesystems with the placeholder property ``zrepl:placeholder``.
+.. _replication-placeholder-property:
+
+**Placeholder filesystems** on the receiving side are regular ZFS filesystems with the placeholder property ``zrepl:placeholder=on``.
 Placeholders allow the receiving side to mirror the sender's ZFS dataset hierachy without replicating every filesystem at every intermediary dataset path component.
 Consider the following example: ``S/H/J`` shall be replicated to ``R/sink/job/S/H/J``, but neither ``S/H`` nor ``S`` shall be replicated.
 ZFS requires the existence of ``R/sink/job/S`` and ``R/sink/job/S/H`` in order to receive into ``R/sink/job/S/H/J``.

docs/usage.rst

@@ -35,6 +35,9 @@ CLI Overview
       - manually abort current replication + pruning of JOB
     * - ``zrepl configcheck``
       - check if config can be parsed without errors
+    * - ``zrepl migrate``
+      - | perform on-disk state / ZFS property migrations
+        | (see :ref:`changelog <changelog>` for details)
 
 .. _usage-zrepl-daemon: