Multi-Repository Gradle Development

When developing features that span multiple Gradle repositories — most commonly when expanding common-module alongside a consuming service — use one of the following approaches depending on the scope of the change.

Option 1: Local Package Directory

Use when: Changes are purely additive and can be isolated to a new package.

Create a new cards.arda.common.lib or cards.arda.common sub-package in the local project’s source tree. This package is temporarily private to that repository. Once stabilized, move it to common-module and publish as a new version. Then remove the local package and update the consuming project’s dependency.

Option 2: Gradle includeBuild (Composite Builds)

Use when: Changes affect existing packages in common-module, or need to be shared with other projects immediately.

Steps

1. Clone common-module to a directory accessible from the consuming project’s directory, but separate from it.

2. In the consuming project, declare the common-module dependency in gradle/libs.versions.toml:

   arda-common-version = "2.0.0"
   arda-common = { module = "cards.arda.common:lib", version.ref = "arda-common-version"}

3. In build.gradle:

   dependencies {
     implementation(libs.arda.common)
   }

4. Tell Gradle to use the local copy using one of these two approaches:

   Command-line parameter:

   ./gradlew --includeBuild=".../path/to/common-module"

   Global init script (recommended for extended development):

   Create ~/.gradle/init.d/common-library.init.gradle.kts:

   gradle.settingsEvaluated {
     val localDependencies = settings.providers.gradleProperty("localDependencies").getOrElse("")
     if (localDependencies.isBlank()) {
       println("Build will not include local files. Define 'localDependencies' property to include them.")
     } else {
       println("Build will include dependencies from $localDependencies.")
       settings.includeBuild(localDependencies)
     }
   }

   Then define the localDependencies property in ~/.gradle/gradle.properties:

   # Absolute path to the module, or path relative to the caller
   localDependencies=.../path/to/common-module

   Important: Comment out or remove localDependencies from gradle.properties when development is complete to avoid including local changes in future builds.

5. Have the IDE refresh its Gradle project configuration to pick up the changes.

Creating Pull Requests

When modifications are complete, create two PRs:

1. A PR for the common-module repository.

2. A PR for the consuming project that:

   • Declares the dependency on the new common-module version.
   • Includes an important admonition linking to the common-module PR:

   > [!IMPORTANT]
   > This PR depends on the changes in [`common-module` #<pull-request-number>](https://github.com/Arda-cards/common-module/pull/<pull-request-number>).
   > Please review and merge it first.