Support legacy data directories (#2846)

book/src/advanced-datadir.md

@@ -13,3 +13,47 @@ lighthouse --network mainnet --datadir /var/lib/my-custom-dir vc
 ```
 The first step creates a `validators` directory under `/var/lib/my-custom-dir` which contains the imported keys and [`validator_definitions.yml`](./validator-management.md).
 After that, we simply run the beacon chain and validator client with the custom dir path.
+
+### Relative Paths
+
+[#2682]: https://github.com/sigp/lighthouse/pull/2682
+[#2846]: https://github.com/sigp/lighthouse/pull/2846
+
+Prior to the introduction of [#2682][] and [#2846][] (releases v2.0.1 and earlier), Lighthouse would
+not correctly parse relative paths from the `lighthouse bn --datadir` flag.
+
+If the user provided a relative path (e.g., `--datadir here` or `--datadir ./here`), the `beacon`
+directory would be split across two paths:
+
+1. `~/here` (in the *home directory*), containing:
+    - `chain_db`
+    - `freezer_db`
+1. `./here` (in the *present working directory*), containing:
+    - `logs`
+    - `network`
+
+All versions released after the fix ([#2846][]) will default to storing all files in the present
+working directory (i.e. `./here`). New users need not be concerned with the old behaviour.
+
+For existing users which already have a split data directory, a backwards compatibility feature will
+be applied. On start-up, if a split directory scenario is detected (i.e. `~/here` exists),
+Lighthouse will continue to operate with split directories. In such a scenario, the following
+harmless log will show:
+
+```
+WARN Legacy datadir location    location: "/home/user/datadir/beacon", msg: this occurs when using relative paths for a datadir location
+```
+
+In this case, the user could solve this warn by following these steps:
+
+1. Stopping the BN process
+1. Consolidating the legacy directory with the new one:
+    - `mv /home/user/datadir/beacon/* $(pwd)/datadir/beacon`
+    - Where `$(pwd)` is the present working directory for the Lighthouse binary
+1. Removing the legacy directory:
+    - `rm -r /home/user/datadir/beacon`
+1. Restarting the BN process
+
+Although there are no known issues with using backwards compatibility functionality, having split
+directories is likely to cause confusion for users. Therefore, we recommend affected users migrate
+to a consolidated directory structure.