Project: Jetpack Compose (General)

This directory contains the libraries that make up Jetpack Compose. All code generated or modified must follow standard AndroidX Compose guidelines.

Project Structure Map

  • Runtime (compose:runtime): The core engine for state management and the composition tree.
  • UI (compose:ui): Orchestration layer for layout, input, graphics, and text primitives.
  • Foundation (compose:foundation): Design-system-agnostic building blocks (e.g., LazyColumn, gestures).
  • Material/Material3 (compose:material): Design-system-specific components implementing Material Design.

General Instructions

  • Formatting: Ensure all modified .kt files are formatted using ./gradlew :ktCheckFile --format --file <file> before committing or calling a change done. Multiple files can be formatted by appending more --file <path> arguments.
  • API Updates: Run ./gradlew <project>:updateApi (and <project>:updateAbiNative where applicable) after any public API change.
  • Context: Always execute commands from the frameworks/support directory.
  • Git: Use git mv when moving files to preserve history. Do not create git commits unless explicitly requested.
  • Build Verification: Ensure changes compile by running ./gradlew <project>:compileDebugKotlinAndroid.

Coding & Performance Standards

  • Multiplatform: Jetpack Compose is a multiplatform project. Implement logic in commonMain whenever possible. Use androidMain or other platform-specific directories only for platform-specific API implementations.
  • Modifiers: Prefer Modifier.Node implementations for high-performance modifiers. Avoid composed {}.
  • API Visibility: Prefer Public APIs where possible. Use @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) only when an API is strictly internal to AndroidX and would be difficult or dangerous for external developers to use correctly.
  • Opt-in APIs: Use @Experimental...Api annotations only when introducing new API surfaces that are likely to remain unstable. When in doubt, don't use them.
  • Dependencies: Avoid introducing new dependencies without verifying their stability and usage elsewhere in the project. Consult libraryversions.toml for version management. Always check with the user when adding a new dependency.

Testing & Documentation

  • Bug Investigations: Always consider whether we can create a test to reproduce the issue described in the bug as closely as possible without making assumptions on what the solution is. Only after we have a test case that represents the bug and is failing should we start trying to fix the code.
  • Samples: Every new public API should have a corresponding sample in the project's samples module. Link it in the KDoc using the @sample tag.
  • Screenshot Tests: Use androidDeviceTest for rendering verification. Screenshot tests must use AndroidXScreenshotTestRule and should be restricted to a specific SDK version (typically SdkSuppress(minSdkVersion = 35, maxSdkVersion = 35)) to ensure deterministic output.
  • JVM Tests: Use standard unit tests in the test directory for non-UI logic.
  • Test Naming: Test classes should be named *Test and placed in the same package as the code they test.