From dc39dc2bd4985a10e8382320d966975f0b9fd212 Mon Sep 17 00:00:00 2001
From: Tyler Gunn <tgunn@google.com>
Date: Wed, 15 Mar 2023 19:29:48 +0000
Subject: [PATCH] Make docs clear that you shouldn't change an existing
 onUpgrade step.

Clarifying the API docs to make it clear to the developer the once a
migration step runs, any errors in that step should be corrected by adding
a new migration step instead of modifying the existing step.

Test: Docs only change
Bug: 258831395
Change-Id: I51874bc215a7edfc270eaf4893147e452beb05d3
---
 .../android/database/sqlite/SQLiteOpenHelper.java   | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/core/java/android/database/sqlite/SQLiteOpenHelper.java b/core/java/android/database/sqlite/SQLiteOpenHelper.java
index 33418006330c4..5e523c0112b1b 100644
--- a/core/java/android/database/sqlite/SQLiteOpenHelper.java
+++ b/core/java/android/database/sqlite/SQLiteOpenHelper.java
@@ -513,6 +513,19 @@ public abstract class SQLiteOpenHelper implements AutoCloseable {
      * This method executes within a transaction.  If an exception is thrown, all changes
      * will automatically be rolled back.
      * </p>
+     * <p>
+     * <em>Important:</em> You should NOT modify an existing migration step from version X to X+1
+     * once a build has been released containing that migration step.  If a migration step has an
+     * error and it runs on a device, the step will NOT re-run itself in the future if a fix is made
+     * to the migration step.</p>
+     * <p>For example, suppose a migration step renames a database column from {@code foo} to
+     * {@code bar} when the name should have been {@code baz}.  If that migration step is released
+     * in a build and runs on a user's device, the column will be renamed to {@code bar}.  If the
+     * developer subsequently edits this same migration step to change the name to {@code baz} as
+     * intended, the user devices which have already run this step will still have the name
+     * {@code bar}.  Instead, a NEW migration step should be created to correct the error and rename
+     * {@code bar} to {@code baz}, ensuring the error is corrected on devices which have already run
+     * the migration step with the error.</p>
      *
      * @param db The database.
      * @param oldVersion The old database version.