CONTRIBUTING.md (6)

9-10: Future-proof the Android SDK prerequisite phrasing

“API level 35 for latest” is time-sensitive and slightly awkward. Prefer “or later” to avoid doc churn.

-- Android SDK (API level 35 for latest)
+- Android SDK (API level 35 or later)

---

14-21: Fix unordered list style to satisfy markdownlint (MD004)

Use dashes consistently for top-level unordered lists.

-* **include-build**: Contains the Gradle plugin and core modules for local development
+- **include-build**: Contains the Gradle plugin and core modules for local development
   - `roborazzi-gradle-plugin`: Gradle plugin that creates record/verify/compare tasks
   - `roborazzi-core`: Core screenshot capture and comparison functionality
-* **Other modules**:
+- **Other modules**:
   - `roborazzi`: Main library module for Android screenshot testing with Robolectric
   - `roborazzi-compose`: Jetpack Compose support for screenshot testing of Composables
   - `roborazzi-junit-rule`: JUnit rule support for simplified test setup
   - `sample-android`: Sample Android app demonstrating usage and for testing changes

---

29-40: Clarify module-scoped task invocation and baseline updates in screenshot tests

In multi-module builds, tasks are often module-scoped; also helpful to note how to intentionally update baselines.

 ```bash
 # First, record baseline screenshots
 ./gradlew recordRoborazziDebug

 # Then, verify screenshots match the baseline
 ./gradlew verifyRoborazziDebug

 # Or, compare and generate diff images
 ./gradlew compareRoborazziDebug

+Note: In multi-module builds, tasks may be scoped per module. Prefix the task with the module path, e.g.:
+
+bash +./gradlew :sample-android:recordRoborazziDebug +./gradlew :sample-android:verifyRoborazziDebug +./gradlew :sample-android:compareRoborazziDebug +
+
+To intentionally update baselines after expected UI changes, re-run the record task.

---

`51-55`: **Add a one-liner for running only “boxed” tests**

This helps speed up local iterations.

```diff
 ```bash
 ./gradlew :sample-android:test

+Only run boxed tests:
+bash +./gradlew :sample-android:test --tests "com.github.takahirom.roborazzi.sample.boxed.*" +

---

`58-67`: **Add debugging flags tip for integration tests**

Handy for diagnosing plugin integration issues locally/CI.

```diff
 ```bash
 # Run from project root
 cd include-build && ./gradlew roborazzi-gradle-plugin:integrationTest && cd ..
 
 # Or run specific tests
 cd include-build && ./gradlew roborazzi-gradle-plugin:integrationTest --tests "*RoborazziGradleProjectTest.record" && cd ..

+Tip: Add --info --stacktrace to the Gradle command for more detailed diagnostics when failures occur.

---

`81-85`: **Tighten troubleshooting paths and add common Gradle tips**

Make the output paths explicit per-module and add actionable flags.

```diff
- - If tests fail, check the generated screenshots in `build/outputs/roborazzi/`
+- If tests fail, check the generated screenshots under each module, e.g. `sample-android/build/outputs/roborazzi/`
 - For integration test failures, check the test reports in `include-build/roborazzi-gradle-plugin/build/reports/`
 - Ensure you're using the correct JDK version (17+)
+- Re-run with more logs: append `--info --stacktrace` to Gradle commands
+- If in doubt, clean and re-run: `./gradlew clean test`

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

CONTRIBUTING.md (7)

7-10: Tighten wording for the Android SDK prerequisite

Replace “for latest” with “or later” for clarity and to avoid temporal ambiguity.

- - Android SDK (API level 35 for latest)
+ - Android SDK (API level 35 or later)

---

14-17: Fix markdownlint MD004: use dashes consistently for unordered lists

Current list markers are mixed. Switch asterisks to dashes to satisfy markdownlint and keep style consistent.

-* **include-build**: Contains the Gradle plugin and core modules for local development
+ - **include-build**: Contains the Gradle plugin and core modules for local development
@@
-* **Other modules**:
+ - **Other modules**:

---

31-38: Prefer explicit Gradle module-qualified tasks for screenshot workflows

Using fully-qualified tasks removes ambiguity and helps when the root doesn’t expose aggregated tasks.

-./gradlew recordRoborazziDebug
+./gradlew :sample-android:recordRoborazziDebug
@@
-./gradlew verifyRoborazziDebug
+./gradlew :sample-android:verifyRoborazziDebug
@@
-./gradlew compareRoborazziDebug
+./gradlew :sample-android:compareRoborazziDebug

---

62-67: Optional: avoid cd by using Gradle’s -p (project dir) flag

This keeps commands copy-paste friendly from anywhere:

For example:

• ./gradlew -p include-build roborazzi-gradle-plugin:integrationTest
• ./gradlew -p include-build roborazzi-gradle-plugin:integrationTest --tests "*RoborazziGradleProjectTest.record"

---

83-85: Polish troubleshooting bullets (punctuation/consistency)

Add periods and avoid contractions for a consistent tone.

-- If tests fail, check the generated screenshots in `build/outputs/roborazzi/`
-- For integration test failures, check the test reports in `include-build/roborazzi-gradle-plugin/build/reports/`
-- Ensure you're using the correct JDK version (17+)
+- If tests fail, check the generated screenshots in `build/outputs/roborazzi/`.
+- For integration test failures, check the test reports in `include-build/roborazzi-gradle-plugin/build/reports/`.
+- Ensure you are using the correct JDK version (17+).

---

1-22: Consider linking Code of Conduct and issue tracker

Adding links near the top reduces friction for contributors:

• Link to issue tracker and discussion channels.
• Link to CODE_OF_CONDUCT.md (if present).

I can scan the repo to confirm presence/paths and propose concrete links.

---

7-22: Documentation aligns with project layout
All modules and test folders exist as documented:

• include-build
• include-build/roborazzi-gradle-plugin
• include-build/roborazzi-core
• roborazzi
• roborazzi-compose
• roborazzi-junit-rule
• sample-android
• sample-android/src/test/java/com/github/takahirom/roborazzi/sample/boxed/
• include-build/roborazzi-gradle-plugin/src/integrationTest/
• Gradle wrapper (./gradlew) present
• Root settings.gradle includes includeBuild("include-build") and the include-build modules

The note “JDK 17 or later” is accurate, but the project currently does not enforce a Java toolchain in Gradle. If you’d like to automatically require Java 17, consider adding to your root build file:

java {
  toolchain {
    languageVersion.set(JavaLanguageVersion.of(17))
  }
}

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

CONTRIBUTING.md (5)

9-11: Tighten prerequisite phrasing for SDK version.

Minor wording nit to avoid ambiguity around “latest.”

-- Android SDK (API level 35 for latest)
+- Android SDK (API level 35 or later)

---

15-23: Standardize list markers to satisfy markdownlint MD004.

Use dashes consistently for unordered lists (the sub-items already use dashes).

-* **include-build**: Contains the Gradle plugin and core modules for local development
+- **include-build**: Contains the Gradle plugin and core modules for local development
   - `roborazzi-gradle-plugin`: Gradle plugin that creates record/verify/compare tasks
   - `roborazzi-core`: Core screenshot capture and comparison functionality
-* **Other modules**:
+- **Other modules**:
   - `roborazzi`: Main library module for Android screenshot testing with Robolectric
   - `roborazzi-compose`: Jetpack Compose support for screenshot testing of Composables
   - `roborazzi-junit-rule`: JUnit rule support for simplified test setup
   - `sample-android`: Sample Android app demonstrating usage and for testing changes

---

32-41: Clarify expected outcomes and how to update baselines.

Call out what to do when diffs are expected so contributors don’t get stuck on verify step.

 ```bash
 # First, record baseline screenshots
 ./gradlew recordRoborazziDebug

 # Then, verify screenshots match the baseline
 ./gradlew verifyRoborazziDebug

 # Or, compare and generate diff images
 ./gradlew compareRoborazziDebug

-Success indicator: BUILD SUCCESSFUL
+Success indicator: BUILD SUCCESSFUL
+
+If changes are intentional and diffs appear, re-record the baseline:
+
+bash +./gradlew recordRoborazziDebug +

Also applies to: 43-44

---

`46-54`: **Make “Boxed Tests” intent crisper.**

Slight rephrase to emphasize isolation and what they validate.


```diff
-Tests that ensure a clean environment for testing Roborazzi's runtime APIs (like `compare`). They manage screenshot files (e.g., by deleting them before execution) to create a predictable state for each test run.
+File-system–isolated tests for Roborazzi’s runtime APIs (e.g., `compare`). They ensure a clean state by managing screenshot files before each run, yielding predictable results.

---

84-86: Point directly to integration test report HTML and add troubleshooting switches.

Make it faster to locate the actionable report and suggest flags commonly needed in Gradle triage.

-- For integration test failures, check the test reports in `include-build/roborazzi-gradle-plugin/build/reports/`
+- For integration test failures, open `include-build/roborazzi-gradle-plugin/build/reports/tests/integrationTest/index.html`
+- When debugging, rerun with `--info --stacktrace` for more context.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

CONTRIBUTING.md (8)

1-86: Nice addition—clear, actionable guide overall.

This CONTRIBUTING.md is a solid first pass: it explains the multi-module layout, how to run screenshot/boxed/integration tests, and a straightforward contribution flow. A few small tweaks below would improve precision, consistency, and reduce potential setup friction.

---

9-11: Tighten prerequisite wording and mention the Gradle Wrapper.

• “API level 35 for latest” is ambiguous; explicitly name the Android version.
• Calling out that contributors should use the included Gradle Wrapper prevents local Gradle/version drift.

Apply:

- - JDK 17 or later
- - Android SDK (API level 35 for latest)
- - Git
+ - JDK 17 or later
+ - Android SDK (API level 35, Android 15)
+ - Git
+ - Gradle: use the included Gradle Wrapper (`./gradlew`); no separate installation required

---

15-23: Fix markdownlint MD004 and unify unordered list style.

Switch the top-level bullets from asterisks to dashes for consistency with the rest of the document and to satisfy markdownlint.

-* **include-build**: Contains the Gradle plugin and core modules for local development
+ - **include-build**: Contains the Gradle plugin and core modules for local development
   - `roborazzi-gradle-plugin`: Gradle plugin that creates record/verify/compare tasks
   - `roborazzi-core`: Core screenshot capture and comparison functionality
-* **Other modules**:
+ - **Other modules**:
   - `roborazzi`: Main library module for Android screenshot testing with Robolectric
   - `roborazzi-compose`: Jetpack Compose support for screenshot testing of Composables
   - `roborazzi-junit-rule`: JUnit rule support for simplified test setup
   - `sample-android`: Sample Android app demonstrating usage and for testing changes

---

30-31: Make the screenshot test description crisper.

Minor style/clarity polish.

-These commands run screenshot tests against the sample modules. If you've made changes to the core library (e.g., in `roborazzi-core`, `roborazzi-compose`), you should verify them by modifying or adding tests within a sample-xx module (like `sample-android`).
+Run screenshot tests against the sample modules. If you change core libraries (e.g., `roborazzi-core`, `roborazzi-compose`), verify them by modifying or adding tests in a sample module (e.g., `sample-android`).

---

32-41: Scope Gradle tasks to the module to avoid ambiguity.

In multi-module builds, unqualified task names can run across multiple projects if present. Prefacing with the module path makes intent explicit.

 ```bash
-# First, record baseline screenshots
-./gradlew recordRoborazziDebug
+# First, record baseline screenshots (module-scoped)
+./gradlew :sample-android:recordRoborazziDebug

-# Then, verify screenshots match the baseline
-./gradlew verifyRoborazziDebug
+# Then, verify screenshots match the baseline
+./gradlew :sample-android:verifyRoborazziDebug

-# Or, compare and generate diff images
-./gradlew compareRoborazziDebug
+# Or, compare and generate diff images
+./gradlew :sample-android:compareRoborazziDebug

Please confirm the exact module(s) intended for these tasks (e.g., only `:sample-android` or additional samples) and adjust prefixes accordingly.

---

`62-68`: **Run integration tests without changing directories.**

Using `-p include-build` keeps commands copy-paste friendly from repo root and avoids subshell quirks. Also prefer single quotes for the test filter on Unix shells.

```diff
 ```bash
-# Run from project root
-cd include-build && ./gradlew roborazzi-gradle-plugin:integrationTest && cd ..
+# Run from project root
+./gradlew -p include-build roborazzi-gradle-plugin:integrationTest

-# Or run specific tests
-cd include-build && ./gradlew roborazzi-gradle-plugin:integrationTest --tests "*RoborazziGradleProjectTest.record" && cd ..
+# Or run specific tests
+./gradlew -p include-build roborazzi-gradle-plugin:integrationTest --tests '*RoborazziGradleProjectTest.record'

If Windows PowerShell is a common contributor shell, you might keep both quoting variants to avoid confusion.

---

`84-86`: **Clarify artifact/report paths per module.**

The current paths are root-relative and may confuse newcomers. Point to the sample module’s outputs and also the standard unit test report.

```diff
-- If tests fail, check the generated screenshots in `build/outputs/roborazzi/`
-- For integration test failures, check the test reports in `include-build/roborazzi-gradle-plugin/build/reports/`
+- If screenshot tests fail, check generated images in `sample-android/build/outputs/roborazzi/`
+- For unit/boxed tests, open `sample-android/build/reports/tests/test/index.html`
+- For Gradle plugin integration test failures, check `include-build/roborazzi-gradle-plugin/build/reports/`
 - Ensure you're using the correct JDK version (17+)

---

72-81: Consider adding “Standards and housekeeping” links (Code of Conduct, issue templates, release notes).

Helps set expectations and reduces back-and-forth on PRs. If these exist in the repo, link them here.

 7.  Create a pull request with a description of your changes
+
+## Standards and Housekeeping
+
+- Please follow the project’s Code of Conduct (link if available).
+- Check existing Issue/PR templates to align with triage labels and required fields.
+- If changes affect public behavior, add/update release notes or changelog entries.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.