Read NoteDb config first from notedb.config
When designing the online migration process, we thought it would be
harmless to write data back to gerrit.config from a running server, and
to assume it would be persisted until the next restart.
Unfortunately, this assumption misses an important use case: when
gerrit.config is managed by Puppet or similar, the file may be
overwritten, losing any migration state.
Solve this problem by reading NoteDb config from notedb.config. This
config is stacked over gerrit.config in the @GerritServerConfig (the
same way that secure.config was prior to extracting the SecureStore
interface), so options may be set in either, but notedb.config takes
precedence. This specifically handles the use case where an admin sets
noteDb.changes.autoMigrate=true in gerrit.config using Puppet: the
migration tool will set autoMigrate=false in notedb.config at the end of
the process, and Puppet can maintain autoMigrate=true in gerrit.config
until an admin (optionally) comes through to copy the final state back
into gerrit.config.
Bug: Issue 7173
Change-Id: I14c69984bfd1c2cb559c73fbf5a4f036972b8cbd
diff --git a/Documentation/note-db.txt b/Documentation/note-db.txt
index 728d630..815cda8 100644
--- a/Documentation/note-db.txt
+++ b/Documentation/note-db.txt
@@ -137,14 +137,23 @@
To continue with the full migration after running the trial migration, use
either the online or offline migration steps as normal. To revert to
ReviewDb-only, remove `noteDb.changes.read` and `noteDb.changes.write` from
-`gerrit.config` and restart Gerrit.
+`notedb.config` and restart Gerrit.
== Configuration
-The migration process works by setting a configuration option in `gerrit.config`
+The migration process works by setting a configuration option in `notedb.config`
for each step in the process, then performing the corresponding data migration.
-In general, users should not set these options manually; this section serves
-primarily as a reference.
+
+Config options are read from `notedb.config` first, falling back to
+`gerrit.config`. If editing config manually, you may edit either file, but the
+migration process itself only touches `notedb.config`. This means if your
+`gerrit.config` is managed with Puppet or a similar tool, it can overwrite
+`gerrit.config` without affecting the migration process. You should not manage
+`notedb.config` with Puppet, but you may copy values back into `gerrit.config`
+and delete `notedb.config` at some later point after completing the migration.
+
+In general, users should not set the options described below manually; this
+section serves primarily as a reference.
- `noteDb.changes.write=true`: During a ReviewDb write, the state of the change
in NoteDb is written to the `note_db_state` field in the `Change` entity.
