Adding User Data Storage documentation.

This document explains the Chromium policies for files in the `User
Data` directory.

BUG=958893

Change-Id: Ia941d3a532cae176a5ed5e5b159f7a72feaef6fe
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1715823
Commit-Queue: Greg Thompson <grt@chromium.org>
Reviewed-by: Julian Pastarmov <pastarmovj@chromium.org>
Cr-Commit-Position: refs/heads/master@{#728507}

docs/README.md

@@ -361,6 +361,7 @@ used when committed.
     install Chromium OS on VMWare.
 *   [User Data Directory](user_data_dir.md) - How the user data and cache
     directories are determined on all platforms.
+*   [User Data Storage](user_data_storage.md) - Policy documentation for files in User Data.
 
 ### Mojo & Services
 *   [Intro to Mojo & Services](mojo_and_services.md) - Quick introduction

docs/user_data_storage.md

@@ -0,0 +1,46 @@
+# User Data Storage
+
+This document explains the Chromium policies for files in the `User Data`
+directory.
+
+[TOC]
+
+## Backward Compatibility
+
+Due to the nature of frequent updates, Chromium must always support loading data
+from files written by previous versions. A good rule of thumb is to leave
+migration code in place for *at least* one year (approximately 9 milestones with
+the current 6-week release cadence). It is not uncommon for clients to update
+from very old versions, so use good judgement for deciding when to remove
+migration code -- if the complexity is low, keep it indefinitely.
+
+## Version Downgrade Processing
+
+In cases where Chromium is run against a `User Data` directory written by a
+newer version, the browser may run to the extent possible with the following
+behaviors:
+
+*   Versioned files that are apparently readable by the old version may be used
+    as-is and modified as needed. For example, a SQLite file containing a table
+    with a compatible version number no higher than that supported by the old
+    version.
+*   Versioned files that cannot be read by the old version and contain user
+    configuration or user generated data are left on-disk unmodified. This
+    allows the data to be used again once the browser is updated. Furthermore,
+    the user should be notified via the [profile error
+    dialog](../chrome/browser/ui/profile_error_dialog.h) that their experience
+    may be degraded. For example, such a browsing session may not accumulate new
+    history database entries.
+*   Versioned files that cannot be read by the old version and contain computed
+    or cached data may be either left on-disk unmodified or deleted and
+    replaced.
+
+## Post-branch Compatibility
+
+Breaking changes in data storage are forbidden once a branch has been created
+for a release. This guarantees that data written by a later build on a release
+branch can be read by previous versions on that same release branch.
+
+## See also
+
+*   [User Data Directory](user_data_dir.md)