Merge "Add sqlite upgrade instructions" into mainandroidx-work-releaseandroidx-window-extensions-releaseandroidx-webkit-releaseandroidx-wear-wear-tooling-preview-releaseandroidx-wear-watchface-releaseandroidx-wear-tiles-releaseandroidx-wear-platform-releaseandroidx-wear-compose-releaseandroidx-viewpager2-releaseandroidx-versionedparcelable-releaseandroidx-vectordrawable-releaseandroidx-transition-releaseandroidx-test-uiautomator-releaseandroidx-profileinstaller-releaseandroidx-platform-releaseandroidx-paging-releaseandroidx-mediarouter-releaseandroidx-media2-releaseandroidx-media-releaseandroidx-main-releaseandroidx-lifecycle-releaseandroidx-hilt-releaseandroidx-graphics-releaseandroidx-g3-releaseandroidx-datastore-releaseandroidx-credential-releaseandroidx-core-releaseandroidx-core-performance-releaseandroidx-core-animation-releaseandroidx-compose-releaseandroidx-compose-material3-releaseandroidx-compose-g3-releaseandroidx-compose-compiler-releaseandroidx-collection-releaseandroidx-car-app-releaseandroidx-browser-releaseandroidx-benchmark-releaseandroidx-annotation-releaseandroidx-annotation-annotation-experimental-releaseandroidx-activity-release

1 files changed, 112 insertions, 0 deletions

diff --git a/README-upgrade.md b/README-upgrade.md
new file mode 100644
index 0000000..060fabd
--- /dev/null
+++ b/README-upgrade.md
@@ -0,0 +1,112 @@
+## Upgrading SQLite
+
+This document lists the steps needed to upgrade the sources in this repository
+with the latest revision from upstream.
+
+## Source Directory
+
+The upgrade takes place on `aosp-main`. The primary directory is below.
+
+```text
+external/sqlite
+```
+
+The upgrade steps are:
+
+*   Select a version for the upgrade.
+*   Download the autoconf amalgamation tarball. For release 3.42.0, the URL is
+    [sqlite-autoconf-3420000.tar.gz](https://sqlite.org/2023/sqlite-autoconf-3420000.tar.gz).
+*   Change to the directory `external/sqlite` in the workspace.
+*   Run the script `UPDATE-SOURCE.bash`. This script is executable. The single
+    argument is the path to the tarball.
+*   Update the internal bookkeeping files (see below).
+
+`UPDATE-SOURCE.bash` may fail if the Android patch cannot be applied cleanly. If
+this happens, correct the patch failures by hand and rebuild the Android patch
+file. Use the script `REBUILD-ANDROID-PATCH.bash` to rebuild the patch file.
+Then rerun `UPDATE-SOURCE.bash`. It is important that `UPDATE-SOURCE.bash` run
+without errors.
+
+A number of files in this directory require special handling.
+
+### README.version
+
+This contains the URL of the source code, the version information, and the bug
+component under which the Android tree was updated. An example is below.
+
+```text
+URL: https://sqlite.org/2023/sqlite-autoconf-3420000.tar.gz
+Version: 3.42.0
+BugComponent: 24950
+```
+
+### METADATA
+
+This file contains a security tag and a reference to the license file. The
+format changes now and then; ensure that it is up to date.
+
+### LICENSE
+
+This file contains the license that allows Android to use the third-party
+software. SQLite is unusual because it has no license: it is in the public
+domain. The current file content is below.
+
+```text
+The author disclaims copyright to this source code.  In place of
+a legal notice, here is a blessing:
+
+   May you do good and not evil.
+   May you find forgiveness for yourself and forgive others.
+   May you share freely, never taking more than you give.
+```
+
+## CTS Version Test
+
+There is a CTS test that verifies the SQLite version. This must be updated as
+well and it must be updated within `aosp-main` at the same time as the source.
+
+```text
+cts/tests/tests/database/src/android/database/sqlite/cts/SQLiteDatabaseTest.java
+```
+
+Update the following two constants (the values below are for SQLite 3.42.0).
+
+```java
+    static final String EXPECTED_MAJOR_MINOR_VERSION = "3.42";
+    static final int EXPECTED_MIN_PATCH_LEVEL = 0;
+```
+
+## Miscellaneous Files
+
+The following files are updated in an internal Android branch (such as `main`)
+
+### package.html
+
+```text
+frameworks/base/core/java/android/database/sqlite/package.html
+```
+
+This is a documentation file that, among other things, maps SQLite versions to
+Android API levels. It should be updated every time SQLite is upgraded and on
+every Android API bump. There is a small problem with API names: Android usually
+prefers not to publicize the new API level until it is official, so care must be
+taken not to expose unofficial API levels through this file.
+
+The current plan for modifying this file when SQLite is upgraded is to add a new
+row, using "latest" as the API level. The file should also be updated
+appropriately when a new API level is formally announced.
+
+This file probably should be modified in an Android branch (not AOSP). That way
+it enters public view with the official release process.
+
+## Recommended Tests
+
+The following tests are recommended before committing an update:
+
+```text
+CtsScopedStorageDeviceOnlyTest
+CtsDatabaseTestCases
+FrameworksCoreTests:android.database
+```
+
+At the time of writing, there are no test failures in the baseline code.