From 27e2cdc97ad8a66697d476a8f2b0d10e70412baf Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 22 Sep 2025 13:10:06 -0400 Subject: [PATCH 1/3] firestore: Improve instructions in `README.md` for rolling your own build of the `firebase-firestore` Gradle artifact --- firebase-firestore/README.md | 131 +++++++++++++++++++++++++++++++++-- 1 file changed, 125 insertions(+), 6 deletions(-) diff --git a/firebase-firestore/README.md b/firebase-firestore/README.md index e71bd024f0f..16902260d08 100644 --- a/firebase-firestore/README.md +++ b/firebase-firestore/README.md @@ -124,16 +124,135 @@ Run below to format Java code: See [here](../README.md#code-formatting) if you want to be able to format code from within Android Studio. -## Build Local Jar of Firestore SDK +## Build firebase-firestore for use in your application. + +It is possible, and, indeed, quite easy, to compile the `firebase-firestore` Gradle artifact from +source and then use that self-compiled artifact in your Android application. + +### Update gradle.properties with a custom version number + +First, edit `firebase-firestore/gradle.properties` and change the "version" to something unique. It +can be especially helpful to append a "-something" suffix to the version name, replacing "something" +with some description of your change. Doing so will give you confidence that you are indeed using +your self-compiled version in your application and not accidentally using an officially-published +version. + +For example, you can change the contents of `firebase-firestore/gradle.properties` from + +``` +version=26.0.2 +latestReleasedVersion=26.0.1 +``` + +to + +``` +version=99.99.99-MyFix1 +latestReleasedVersion=26.0.1 +``` + +### Build the `firebase-firestore` Gradle artifact + +Then, build the `firebase-firestore` Gradle artifact by running: ```bash -./gradlew -PprojectsToPublish="firebase-firestore" publishReleasingLibrariesToMavenLocal +./gradlew :firebase-firestore:publishToMavenLocal +``` + +### Add mavenLocal() repository to your Android app + +In order to take a dependency on the self-compiled Gradle `firebase-firestore` artifact, first add +`mavenLocal()` to the +[`dependencyResolutionManagement.repositories`](https://docs.gradle.org/current/userguide/declaring_repositories.html) +section of your Android application's `settings.gradle` or `settings.gradle.kts` file. + +For example, you would change something like + +```kotlin +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + google() + mavenCentral() + } +} +``` + +to + +```kotlin +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + google() + mavenCentral() + mavenLocal() // Add this line to use the artifacts published by `publishToMavenLocal` + } +} +``` + +### Change the firebase-firestore dependency in your Android app + +Then, edit your Android application's `build.gradle` or `build.gradle.kts` to use the self-compiled +Gradle `firebase-firestore` artifact. + +For example, you would change something like + +```kotlin +dependencies { + implementation(platform("com.google.firebase:firebase-bom:34.3.0")) + implementation("com.google.firebase:firebase-firestore") + // ... the rest of your application's dependencies +} ``` -Developers may then take a dependency on these locally published versions by adding the -`mavenLocal()` repository to your -[repositories block](https://docs.gradle.org/current/userguide/declaring_repositories.html) in your -app module's build.gradle. +to + +```kotlin +dependencies { + implementation(platform("com.google.firebase:firebase-bom:34.3.0")) + // Use the custom version you set in gradle.properties in the next line. + implementation("com.google.firebase:firebase-firestore:99.99.99-MyFix1") + // ... the rest of your application's dependencies +} +``` + +### (Optional) Log the firebase-firestore version to logcat + +It can be helpful to see in the logs which exact version of the `firebase-firestore` Gradle artifact +your application is using. This increases the confidence that your application is indeed using the +custom, self-compiled artifact rather than an official artifact. + +To do this, simply add a line like the following somewhere in your Android application: + +```kotlin +android.util.Log.i("FirestoreVersion", com.google.firebase.firestore.BuildConfig.VERSION_NAME) +``` + +### (Rarely required) Self-compile dependencies of firebase-firestore + +The `firebase-firestore` Gradle artifact includes dependencies on a few peer modules in the +`firebase-android-sdk` repository. Although rare, sometimes you want, or need, to include local +changes to these dependencies in your self-compiled build. + +At the time of writing, the peer dependencies of `firebase-firestore` include: + +- `firebase-common` +- `firebase-components` +- `firebase-database-collection` +- `protolite-well-known-types` + +For purposes of example, suppose there is a local change to `firebase-common` that you want your +self-compiled `firebase-firestore` artifact to pick up. Follow the steps below to do this, adapting +the steps as appropriate if your specific case uses a _different_ dependency. + +1. Edit `firebase-common/gradle.properties`, changing the verson to something like `99.99.99`. +2. Compile and publish the `firebase-common` Gradle artifact by running: + `./gradlew :firebase-common:publishToMavenLocal` +3. Edit `firebase-firestore/firebase-firestore.gradle` to use a _project_ dependency on the + artifact. For example, change `api(libs.firebase.common)` to `api(project(":firebase-common"))` +4. Compile and publish the `firebase-firestore` Gradle artifact as documented above, namely, by + running `./gradlew :firebase-firestore:publishToMavenLocal` ## Misc From 8c16a06c7278c8d8a51f4ba9f9866c7b47e15edb Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 22 Sep 2025 13:17:39 -0400 Subject: [PATCH 2/3] fixes --- firebase-firestore/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/firebase-firestore/README.md b/firebase-firestore/README.md index 16902260d08..369ff6f7b18 100644 --- a/firebase-firestore/README.md +++ b/firebase-firestore/README.md @@ -124,7 +124,7 @@ Run below to format Java code: See [here](../README.md#code-formatting) if you want to be able to format code from within Android Studio. -## Build firebase-firestore for use in your application. +## Roll your own build of firebase-firestore for use in your application It is possible, and, indeed, quite easy, to compile the `firebase-firestore` Gradle artifact from source and then use that self-compiled artifact in your Android application. @@ -161,7 +161,7 @@ Then, build the `firebase-firestore` Gradle artifact by running: ### Add mavenLocal() repository to your Android app -In order to take a dependency on the self-compiled Gradle `firebase-firestore` artifact, first add +In order to take a dependency on the self-compiled `firebase-firestore` Gradle artifact, first add `mavenLocal()` to the [`dependencyResolutionManagement.repositories`](https://docs.gradle.org/current/userguide/declaring_repositories.html) section of your Android application's `settings.gradle` or `settings.gradle.kts` file. @@ -186,7 +186,7 @@ dependencyResolutionManagement { repositories { google() mavenCentral() - mavenLocal() // Add this line to use the artifacts published by `publishToMavenLocal` + mavenLocal() // Add this line to use artifacts published by `publishToMavenLocal` } } ``` @@ -249,8 +249,9 @@ the steps as appropriate if your specific case uses a _different_ dependency. 1. Edit `firebase-common/gradle.properties`, changing the verson to something like `99.99.99`. 2. Compile and publish the `firebase-common` Gradle artifact by running: `./gradlew :firebase-common:publishToMavenLocal` -3. Edit `firebase-firestore/firebase-firestore.gradle` to use a _project_ dependency on the - artifact. For example, change `api(libs.firebase.common)` to `api(project(":firebase-common"))` +3. If necessary, edit `firebase-firestore/firebase-firestore.gradle` to use a _project_ dependency + on the artifact. For example, change `api(libs.firebase.common)` to + `api(project(":firebase-common"))` 4. Compile and publish the `firebase-firestore` Gradle artifact as documented above, namely, by running `./gradlew :firebase-firestore:publishToMavenLocal` From e6a7a57112608e79b20a63f37982200dbf9d8267 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 22 Sep 2025 14:02:03 -0400 Subject: [PATCH 3/3] gemini re-write --- firebase-firestore/README.md | 118 +++++++++++------------------------ 1 file changed, 36 insertions(+), 82 deletions(-) diff --git a/firebase-firestore/README.md b/firebase-firestore/README.md index 369ff6f7b18..fefb89db18c 100644 --- a/firebase-firestore/README.md +++ b/firebase-firestore/README.md @@ -124,49 +124,40 @@ Run below to format Java code: See [here](../README.md#code-formatting) if you want to be able to format code from within Android Studio. -## Roll your own build of firebase-firestore for use in your application +## Using a custom build in your application -It is possible, and, indeed, quite easy, to compile the `firebase-firestore` Gradle artifact from -source and then use that self-compiled artifact in your Android application. +To build `firebase-firestore` from source and use the resulting artifact in your +Android application, follow these steps. -### Update gradle.properties with a custom version number +### 1. Set a custom version -First, edit `firebase-firestore/gradle.properties` and change the "version" to something unique. It -can be especially helpful to append a "-something" suffix to the version name, replacing "something" -with some description of your change. Doing so will give you confidence that you are indeed using -your self-compiled version in your application and not accidentally using an officially-published -version. - -For example, you can change the contents of `firebase-firestore/gradle.properties` from +In `firebase-firestore/gradle.properties`, change the `version` to a unique +value. Appending a suffix makes it easy to identify your custom build. +For example, change: ``` version=26.0.2 latestReleasedVersion=26.0.1 ``` -to - +To: ``` version=99.99.99-MyFix1 latestReleasedVersion=26.0.1 ``` -### Build the `firebase-firestore` Gradle artifact - -Then, build the `firebase-firestore` Gradle artifact by running: +### 2. Build the artifact +Build and publish the artifact to your local Maven repository: ```bash ./gradlew :firebase-firestore:publishToMavenLocal ``` -### Add mavenLocal() repository to your Android app - -In order to take a dependency on the self-compiled `firebase-firestore` Gradle artifact, first add -`mavenLocal()` to the -[`dependencyResolutionManagement.repositories`](https://docs.gradle.org/current/userguide/declaring_repositories.html) -section of your Android application's `settings.gradle` or `settings.gradle.kts` file. +### 3. Update your app's repositories -For example, you would change something like +In your application's `settings.gradle` or `settings.gradle.kts` file, add +`mavenLocal()` to the `repositories` block within +`dependencyResolutionManagement`. ```kotlin dependencyResolutionManagement { @@ -174,86 +165,49 @@ dependencyResolutionManagement { repositories { google() mavenCentral() + mavenLocal() // Add this line } } ``` -to - -```kotlin -dependencyResolutionManagement { - repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) - repositories { - google() - mavenCentral() - mavenLocal() // Add this line to use artifacts published by `publishToMavenLocal` - } -} -``` +### 4. Update your app's dependencies -### Change the firebase-firestore dependency in your Android app - -Then, edit your Android application's `build.gradle` or `build.gradle.kts` to use the self-compiled -Gradle `firebase-firestore` artifact. - -For example, you would change something like +In your application's `build.gradle` or `build.gradle.kts` file, update the +`firebase-firestore` dependency to use the custom version you set in step 1. ```kotlin dependencies { implementation(platform("com.google.firebase:firebase-bom:34.3.0")) - implementation("com.google.firebase:firebase-firestore") - // ... the rest of your application's dependencies -} -``` - -to - -```kotlin -dependencies { - implementation(platform("com.google.firebase:firebase-bom:34.3.0")) - // Use the custom version you set in gradle.properties in the next line. + // Use the custom version from gradle.properties implementation("com.google.firebase:firebase-firestore:99.99.99-MyFix1") - // ... the rest of your application's dependencies + // ... other dependencies } ``` -### (Optional) Log the firebase-firestore version to logcat - -It can be helpful to see in the logs which exact version of the `firebase-firestore` Gradle artifact -your application is using. This increases the confidence that your application is indeed using the -custom, self-compiled artifact rather than an official artifact. +### Optional: Verify the version at runtime -To do this, simply add a line like the following somewhere in your Android application: +To confirm that your application is using the custom artifact, you can log its +version. Add the following code to your application: ```kotlin android.util.Log.i("FirestoreVersion", com.google.firebase.firestore.BuildConfig.VERSION_NAME) ``` -### (Rarely required) Self-compile dependencies of firebase-firestore - -The `firebase-firestore` Gradle artifact includes dependencies on a few peer modules in the -`firebase-android-sdk` repository. Although rare, sometimes you want, or need, to include local -changes to these dependencies in your self-compiled build. - -At the time of writing, the peer dependencies of `firebase-firestore` include: - -- `firebase-common` -- `firebase-components` -- `firebase-database-collection` -- `protolite-well-known-types` +### Building with local module dependencies -For purposes of example, suppose there is a local change to `firebase-common` that you want your -self-compiled `firebase-firestore` artifact to pick up. Follow the steps below to do this, adapting -the steps as appropriate if your specific case uses a _different_ dependency. +If your changes require building other modules in this repository (like +`firebase-common`), you must build and publish them locally as well. -1. Edit `firebase-common/gradle.properties`, changing the verson to something like `99.99.99`. -2. Compile and publish the `firebase-common` Gradle artifact by running: - `./gradlew :firebase-common:publishToMavenLocal` -3. If necessary, edit `firebase-firestore/firebase-firestore.gradle` to use a _project_ dependency - on the artifact. For example, change `api(libs.firebase.common)` to - `api(project(":firebase-common"))` -4. Compile and publish the `firebase-firestore` Gradle artifact as documented above, namely, by - running `./gradlew :firebase-firestore:publishToMavenLocal` +1. In the dependency's directory (e.g., `firebase-common/`), edit + `gradle.properties` to set a unique version. +2. Publish the dependency to Maven Local: + ```bash + ./gradlew :firebase-common:publishToMavenLocal + ``` +3. In `firebase-firestore/firebase-firestore.gradle`, ensure the dependency is a + project dependency. For example, change `api(libs.firebase.common)` to + `api(project(":firebase-common"))`. +4. Build and publish the `firebase-firestore` artifact as described in step 2. ## Misc