https://github.com/j-roskopf/ComposeGuard
A Gradle plugin for detecting regressions in Jetpack Compose
https://github.com/j-roskopf/ComposeGuard
Last synced: 3 months ago
JSON representation
A Gradle plugin for detecting regressions in Jetpack Compose
- Host: GitHub
- URL: https://github.com/j-roskopf/ComposeGuard
- Owner: j-roskopf
- License: mit
- Created: 2024-05-15T10:29:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-28T17:01:21.000Z (about 1 year ago)
- Last Synced: 2024-05-29T05:15:03.672Z (about 1 year ago)
- Language: Kotlin
- Size: 981 KB
- Stars: 57
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-list - j-roskopf/ComposeGuard - A Gradle plugin for detecting regressions in Jetpack Compose / Compose Multiplatform (Kotlin)
README
Compose Guard
A gradle plugin for detecting regressions in Jetpack Compose / Compose Multiplatform:
* New restartable but not skippable @Composables are added
* New unstable classes are added (only triggers if they are used as a @Composable parameter)
* New @dynamic properties are added
* New unstable parameters are added to a @Composable
In an Android project, Compose Guard adds 3 tasks:
* `ComposeCompilerGenerate` (example `./gradlew releaseComposeCompilerGenerate`)
- Generate golden compose metrics to compare against
* `ComposeCompilerCheck` (example `./gradlew releaseComposeCompilerCheck`)
- Generates new metrics and compares against golden values
* `./gradlew composeCompilerClean`
- Deletes all compiler metrics
In a Multiplatform project, Compose Guard adds the same 2 `Check` and `Generate` tasks (as well as a root `composeCompilerClean` task) for each supported target following the pattern `ComposeCompilerGenerate`
* `ComposeCompilerGenerate`
- Examples: `./gradlew androidReleaseComposeCompilerGenerate`, `./gradlew jvmComposeCompilerGenerate`, ` ./gradlew iosArm64ComposeCompilerGenerate`, `./gradlew jsComposeCompilerGenerate`, `./gradlew wasmJsComposeCompilerGenerate`
- Generate golden compose metrics to compare against
* `ComposeCompilerCheck`
- Examples: `./gradlew androidReleaseComposeCompilerCheck`, `./gradlew jvmComposeCompilerCheck`, `./gradlew iosArm64ComposeCompilerCheck`, `./gradlew jsComposeCompilerCheck`, `./gradlew wasmJsComposeCompilerCheck`
- Generates new metrics and compares against golden values
* `./gradlew composeCompilerClean`
- Deletes all compiler metrics
## Platforms
 |  |  | 
:----: | :----: |:----------------------------------------------------------------------------------:| :----:
✅ | ✅ | ✅ | ✅
## Adding To Your Project
Available via Maven Central - 
In your root build file:
```kotlin
plugins {
id("com.joetr.compose.guard") version "" apply false
}
```
In any module you want to apply checks:
```kotlin
plugins {
id("com.joetr.compose.guard")
}
```
## Configuring Compose Guard
Each check that is performed has the ability to be turned off in case it is not useful to you.
```kts
composeGuardCheck {
errorOnNewDynamicProperties = false // defaults to true
errorOnNewRestartableButNotSkippableComposables = false // defaults to true
errorOnNewUnstableClasses = false // defaults to true
errorOnNewUnstableParams = false // defaults to true
/**
* In strong skipping mode (https://developer.android.com/develop/ui/compose/performance/stability/strongskipping)
* you may not care about new unstable params if the composable is already skippable
*/
ignoreUnstableParamsOnSkippableComposables = true // defaults to false
/**
* If baseline metrics are missing, the check task will no longer fail and will instead just report
* all checks.
*/
reportAllOnMissingBaseline = true // defaults to false
/**
* Stability cannot be automatically inferred across module boundaries. With this option enabled,
* any properties marked as 'runtime' stability will be inferred to be unstable. If you can guarantee properties
* as stable across module boundaries, mark them as so.
*/
assumeRuntimeStabilityAsUnstable = true // defaults to false
}
```
The output directory of the golden metrics has the ability to be configured as well.
```kotlin
composeGuardGenerate {
outputDirectory = layout.projectDirectory.dir("custom_dir").asFile
}
```
Additionally, if you would prefer complete control over how the metrics are generated, you can disable this plugin from configuring the Kotlin compile task.
This is intended advanced users that prefer compiler performance over easy baseline generation.
With this set, the plugin no longer configures anything in the Kotlin compile task.
So an end user would be responsible for generating the golden metrics and the check metrics before running the check task.
```kotlin
composeGuard {
configureKotlinTasks = false // defaults to true
}
```
## Signing locally
This is required to test.
* Install gnupg - https://formulae.brew.sh/formula/gnupg
* Generate a key - https://central.sonatype.org/publish/requirements/gpg/#generating-a-key-pair
* `gpg --full-generate-key`
* List keys and grab newly generated key (40 digits)
* `gpg --list-keys`
* `gpg --export-secret-keys THE_KEY_THAT_YOU_JUST_GENERATED > composeguard.gpg`
* Modify your gradle home `gradle.properties` with the following:
```
signing.keyId=LAST_8_DIGITS_OF_KEY
signing.password=PASSWORD_USED_TO_GENERATE_KEY
signing.secretKeyRingFile=/Users/YOURUSERNAME/.gnupg/composeguard.gpg (or wherever you stored the keyring you generated earlier)
```
## Binary Compatibility Validator
This project uses [this](https://github.com/Kotlin/binary-compatibility-validator) tool to ensure the public binary API wasn't changed in a way that makes it binary incompatible.
The tool allows dumping binary API of a JVM part of a Kotlin library that is public in the sense of Kotlin visibilities.
To generate a new binary dump, run `./gradlew apiDump` in the root of the project.