Fix the upgrade notes of the Gerrit v3.15.0 release notes The upgrade instructions were carried over from v3.14 and did not match v3.15: - The zero-downtime upgrade and the downgrade also cover v3.13 - Detail the schema 185 -> 187 migrations (186 is a no-op) and why the Changes index v90 needs a full reindex - Add the Java 25 prerequisite, the missing init step to the offline upgrade and an online upgrade with limited downtime - Explain that gerrit.experimentalRollingUpgrade is needed during a rolling upgrade, as v3.13/v3.14 refuse to start on schema 187 - Add a Downgrade section - List two 3.15 bugs as known issues Change-Id: I2cf67cf61da11cfe21ccda71ec91dc88b77f09b9
diff --git a/pages/site/releases/3.15.md b/pages/site/releases/3.15.md index 53edc15..8102cda 100644 --- a/pages/site/releases/3.15.md +++ b/pages/site/releases/3.15.md
@@ -167,25 +167,58 @@ ## Important Notes +### Prerequisites + +Install a Java 25 runtime on all the Gerrit servers before upgrading: the +released `gerrit.war` needs Java 25, see [Java 25](#java-25). +Also update `container.javaHome` setting in `gerrit.config` to point to the new +`JAVA_HOME` location + ### Schema and index changes -Gerrit schema version is updated to `187`. +Gerrit schema version is updated to `187` (Gerrit v3.12/v3.13/v3.14 are all +on `185`): -The Changes index has been upgraded from `v88` to `v90`. +* `Schema_186` is a no-op. +* `Schema_187` grants the `aiReview` permission to Registered Users on + `refs/heads/*` in `All-Projects`, unless an `aiReview` rule already exists + there, so that the switch to the default-deny model keeps the previous + behavior. + +The Changes index has been upgraded to `v90` (Gerrit v3.12/v3.13 are on `v87`, v3.14 +on `v88`) and requires a reindex: `v89` adds the `unmet-requirement` and +`unsatisfied-requirement-count` fields, and `v90` adds the `file-count` field. The +Accounts, Groups and Projects index versions are unchanged. ### Offline upgrade - Stop Gerrit - Download the new `gerrit.war` and move it to `$GERRIT_SITE/bin` - Extract all the plugins from `gerrit.war` and move the ones needed into `$GERRIT_SITE/plugins` +- Run init to apply the schema migrations: + `java -jar $GERRIT_SITE/bin/gerrit.war init --batch -d $GERRIT_SITE` - Run the full reindex: `java -jar $GERRIT_SITE/bin/gerrit.war reindex --index changes -d $GERRIT_SITE` - Start Gerrit +### Upgrade with limited downtime and online reindex + +- Stop Gerrit +- Download the new `gerrit.war` and move it to `$GERRIT_SITE/bin` +- Update `container.javaHome` setting in `gerrit.config` to point to the new `JAVA_HOME` location +- Extract all the plugins from `gerrit.war` and move the ones needed into `$GERRIT_SITE/plugins` +- Run init to apply the schema migrations: + `java -jar $GERRIT_SITE/bin/gerrit.war init --batch -d $GERRIT_SITE` +- Start Gerrit + +Gerrit keeps serving searches from the existing `v87`/`v88` Changes index and +builds the `v90` index in the background, switching to it once complete. This +requires. + ### Online upgrade with zero-downtime -Gerrit v3.15.x supports zero-downtime upgrade from Gerrit v3.13 when configured -using a +Gerrit v3.15.x supports zero-downtime upgrade from Gerrit v3.12, v3.13 or v3.14 when +configured using a [high-availability](https://gerrit.googlesource.com/plugins/high-availability/+/refs/heads/master/README.md) setup. @@ -196,7 +229,7 @@ The zero-downtime upgrade process for high-availability setups consists of the following steps ([demo](https://youtu.be/vK5qsb0W7q4)): -1. Have Gerrit servers running v3.13 in high-availability +1. Have Gerrit servers running v3.12/v3.13/v3.14 in high-availability configuration, healthy and able to handle the incoming traffic properly. 2. Set one of the Gerrit servers to unhealthy. 3. Shutdown the Gerrit server, update gerrit.war, plugins and libs to v3.15.x and start Gerrit again. @@ -206,6 +239,34 @@ it was down before directing traffic to it. 6. Repeat steps 2 to 6 for each of the remaining Gerrit servers. +> **NOTE**: The schema version changes from `185` to `187`. Set + [`gerrit.experimentalRollingUpgrade = true`](https://gerrit-documentation.storage.googleapis.com/Documentation/3.15.0/config-gerrit.html#gerrit.experimentalRollingUpgrade) + on all the Gerrit servers for the duration of the upgrade; without it, the + v3.13/v3.14 servers refuse to start once the first server has migrated the schema. + Remove the setting once all the servers run v3.15. + +### Downgrade + +Downgrade to Gerrit v3.12, v3.13 or v3.14 is possible, but requires the following manual steps: + +1. Stop Gerrit +2. Set `gerrit.experimentalRollingUpgrade = true` in `gerrit.config`: v3.13/v3.14 + refuses to start on schema version `187` otherwise +3. Rollback the gerrit.war and plugins to the previous v3.13/v3.14 version +4. Run the full reindex with the v3.13/v3.14 `gerrit.war`, because the old + `v87`/`v88` Changes index does not contain the updates made while running + v3.15: + `java -jar $GERRIT_SITE/bin/gerrit.war reindex --index changes -d $GERRIT_SITE` +5. Start Gerrit + +The migration to `Schema_187` may have added the `aiReview` grant in +`All-Projects` if no other `aiReview` permission had been specified. +This should be removed, but it may be kept regardless as: + +* Gerrit v3.14 applies it, so Registered Users keep AI Review on + `refs/heads/*` as before. +* Gerrit v3.12/v3.13 does not know the `aiReview` permission and ignores it. + ### Known issues * [Issue 309098227](https://issues.gerritcodereview.com/issues/309098227) [Change 360646](https://gerrit-review.googlesource.com/360646):