Migrate commcare-core from sibling directory to git submodule

[avazirna]

Product Description

No user-facing changes. This is an infrastructure change to how commcare-core is integrated into commcare-android.

Technical Summary

Replaces the sibling-directory local Gradle module dependency on commcare-core (../commcare-core/) with a git submodule at libs/commcare-core/, following the same pattern already used by formplayer.

Motivation:

• Simpler onboarding: git clone --recurse-submodules gets everything in one step — no manual sibling directory setup
• Simpler CI: actions/checkout with submodules: true replaces the Python checkout_cross_request_repo.py script
• Cleaner project structure: commcare-core lives inside the repo rather than requiring a specific sibling directory layout

Key changes:

• Added commcare-core as a git submodule at libs/commcare-core/ tracking master
• Updated settings.gradle to point to libs/commcare-core instead of ../commcare-core
• Updated CI workflow: replaced the 4-step Python cross-request script with submodules: true on actions/checkout
• Updated AGENTS.md, README.md, and app/build.gradle to reflect new setup instructions
• browserstack-tests job unchanged (only uses pre-built artifacts)

Cross-repo PR workflow after this change:
Developers update the submodule pointer in the commcare-android PR to test against a commcare-core feature branch. Once the commcare-core PR merges, the pointer is updated to the merged master commit.

Benchmarked against: formplayer's existing git submodule setup for commcare-core.

Safety Assurance

Safety story

• Gradle project resolution verified locally (./gradlew projects succeeds)
• The Gradle module name :commcare-core is unchanged, so app/build.gradle dependencies (implementation and testImplementation testsAsJar) require no changes
• Mirrors a proven pattern already in production with formplayer

Automated test coverage

• CI workflow will validate the submodule checkout works end-to-end on first PR run
• Existing unit and instrumentation test suites are unaffected

QA Plan

• Verify CI passes on this PR (build + tests + artifact generation)
• Verify a fresh clone with --recurse-submodules works
• Verify git submodule update --init works for existing checkouts

Labels and Review

• Do we need to enhance the manual QA test coverage ? If yes, RELEASES.md is updated accordingly
• Does the PR introduce any major changes worth communicating ? If yes, RELEASES.md is updated accordingly
• Risk label is set correctly
• The set of people pinged as reviewers is appropriate for the level of risk of the change

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request migrates commcare-core from a sibling directory (../commcare-core) to a git submodule located at libs/commcare-core. The changes update the Gradle build configuration to reference the new submodule location, modify the GitHub Actions workflow to enable submodule checkout while removing custom Python scripts, and update developer documentation to reflect the new repository structure and cloning process.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: migrating commcare-core from a sibling directory to a git submodule, which is confirmed by all file changes.
Description check	✅ Passed	The description covers all required template sections: Product Description (no user-facing changes), Technical Summary (motivation, key changes, cross-repo workflow), and Safety Assurance (safety story, test coverage, QA plan).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch migrate-commcare-core-to-git-submodule

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

docs/superpowers/plans/2026-03-11-commcare-core-git-submodule.md (1)

36-40: Add language specifiers to fenced code blocks.

Several code blocks throughout this document lack language specifiers (lines 37, 53, etc.). While this doesn't affect functionality, it improves readability and satisfies markdown lint rules.

For expected output blocks, use text:

-```
+```text
 Cloning into '/Users/.../commcare-android/libs/commcare-core'...

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/superpowers/plans/2026-03-11-commcare-core-git-submodule.md` around
lines 36 - 40, Several fenced code blocks in the markdown (notably the expected
output block containing "Cloning into
'/Users/.../commcare-android/libs/commcare-core'...") are missing language
specifiers; update those fenced blocks to use the text language (i.e., change
``` to ```text) so expected-output snippets render and satisfy markdown linting.

.github/workflows/commcare-android-pr-workflow.yml (1)

14-17: Consider adding submodules: true to the linter workflow's checkout step.

The linter.yml file at line 22 uses actions/checkout@v4 without submodules: true. Since the codebase has extensive imports from org.commcare.core.* (network, encryption, parsing, etc.), the commcare-core submodule may be needed if the linter performs deep static analysis on Java/Kotlin code. Currently, libs/commcare-core/ will be empty during linting.

However, since super-linter (v8.2.1) is primarily a style/format linter and only validates changed files (VALIDATE_ALL_CODEBASE: false), it may work without the submodule. Update this only if you experience linting failures related to unresolved imports or type checking.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/commcare-android-pr-workflow.yml around lines 14 - 17, The
linter workflow's checkout step (actions/checkout@v4 in linter.yml) does not
fetch git submodules so libs/commcare-core/ may be empty during linting; update
the checkout step used by linter.yml to include submodules: true (same key used
in .github/workflows/commcare-android-pr-workflow.yml) so the commcare-core
submodule is populated before super-linter runs, ensuring imports under
org.commcare.core are available to any deeper static analysis.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.github/workflows/commcare-android-pr-workflow.yml:
- Around line 14-17: The linter workflow's checkout step (actions/checkout@v4 in
linter.yml) does not fetch git submodules so libs/commcare-core/ may be empty
during linting; update the checkout step used by linter.yml to include
submodules: true (same key used in
.github/workflows/commcare-android-pr-workflow.yml) so the commcare-core
submodule is populated before super-linter runs, ensuring imports under
org.commcare.core are available to any deeper static analysis.

In `@docs/superpowers/plans/2026-03-11-commcare-core-git-submodule.md`:
- Around line 36-40: Several fenced code blocks in the markdown (notably the
expected output block containing "Cloning into
'/Users/.../commcare-android/libs/commcare-core'...") are missing language
specifiers; update those fenced blocks to use the text language (i.e., change
``` to ```text) so expected-output snippets render and satisfy markdown linting.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 31574c63-ec6b-423f-aa39-798c23b82df0

📥 Commits

Reviewing files that changed from the base of the PR and between ba67e85 and be73986.

📒 Files selected for processing (8)

• .github/workflows/commcare-android-pr-workflow.yml
• .gitmodules
• AGENTS.md
• README.md
• app/build.gradle
• docs/superpowers/plans/2026-03-11-commcare-core-git-submodule.md
• libs/commcare-core
• settings.gradle

💤 Files with no reviewable changes (1)

• app/build.gradle

[conroy-ricketts]

Looks like we can delete this file now?

[avazirna]

yes