Merge pull request #4 from AckeeCZ/chore/update-project

Update project

Author: mottljan

.github/actions/basic-preflight-check/action.yml

@@ -0,0 +1,34 @@
+# This action's steps must be synced with preMergeRequestCheck Gradle task's checks to ensure that
+# we check required stuff on CI and at the same time developers can run the Gradle task to verify their
+# changes before making a PR. This action can be used in more workflows than just PR, since these
+# basic pre merge request checks (Detekt, library tests, ...) are fundamental to be checked in
+# basically all situations like merging, pushing to dev, etc.
+name: Basic preflight check
+description: Action that contains basic checks like running Detekt or library tests that are common to multiple workflows
+
+runs:
+  using: "composite"
+  steps:
+    - name: Detekt
+      shell: bash
+      run: ./gradlew detekt
+
+    - name: Assemble release variant
+      shell: bash
+      run: ./gradlew assembleRelease
+
+    - name: Library tests
+      shell: bash
+      run: ./gradlew testDebugUnitTest -x :sample:testDebugUnitTest
+
+    - name: Sample app snapshot tests
+      shell: bash
+      run: ./gradlew :sample:verifyPaparazziDebug
+
+    - name: Binary compatibility check
+      shell: bash
+      run: ./gradlew apiCheck
+
+    - name: Build logic tests
+      shell: bash
+      run: ./gradlew build-logic:test

.github/actions/setup/action.yml

@@ -0,0 +1,11 @@
+name: Setup
+description: Action that performs common setup tasks like setting up Java
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up JDK 17
+      uses: actions/setup-java@v4
+      with:
+        java-version: '17'
+        distribution: 'corretto'

.github/workflows/deploy.yml

@@ -1,22 +1,59 @@
-name: Deploy lib to Maven Central
+name: Deploy
 
 on:
   push:
     tags:
-      - '*'
+      # Gradle build logic relies on this tag format, so if you need to change it, you need to change
+      # it there as well.
+      - bom-*
+
+env:
+  GPG_KEY: ${{ secrets.ANDROID_GPG_KEY }}
+  GPG_PASSWORD: ${{ secrets.ANDROID_SIGNING_PASSWORD }}
+  MAVEN_USERNAME: ${{ secrets.ANDROID_MAVEN_CENTRAL_USERNAME }}
+  MAVEN_PASSWORD: ${{ secrets.ANDROID_MAVEN_CENTRAL_PASSWORD }}
 
 jobs:
-  build:
+  # This job's steps must be synced with prePublishCheck Gradle task's checks to ensure that
+  # we check required stuff on CI and at the same time developers can run the Gradle task to verify
+  # their changes before publishing.
+  preflight_checks:
     runs-on: ubuntu-latest
+    steps:
+      # actions/checkout can't be included in the composite setup action, because the composite
+      # action needs to be first checked out by the checkout action.
+      - name: Check out code
+        uses: actions/checkout@v5
+        with:
+          # Fetch all history including all tags, because we need previous release tag for verifyPublishing task
+          fetch-depth: 0
+
+      - name: Setup
+        uses: ./.github/actions/setup
+        
+      - name: Basic preflight checks
+        uses: ./.github/actions/basic-preflight-check
+
+      - name: Verify publishing
+        run: ./gradlew verifyPublishing
 
+      - name: Verify BOM version
+        run: ./gradlew verifyBomVersion
+
+  publish:
+    needs: preflight_checks
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed by softprops/action-gh-release to be able to create a release
+      contents: write
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v2
+      # actions/checkout can't be included in the composite setup action, because the composite
+      # action needs to be first checked out by the checkout action.
+      - name: Check out code
+        uses: actions/checkout@v5
 
-      - name: Set up JDK 17
-        uses: actions/setup-java@v1
-        with:
-          java-version: '17'
+      - name: Setup
+        uses: ./.github/actions/setup
 
       - name: Publish to Maven Central
         run: |
@@ -25,8 +62,8 @@ jobs:
             -PsigningInMemoryKeyPassword=$GPG_PASSWORD \
             -PmavenCentralUsername=$MAVEN_USERNAME \
             -PmavenCentralPassword=$MAVEN_PASSWORD
-        env:
-          GPG_KEY: ${{ secrets.ANDROID_GPG_KEY }}
-          GPG_PASSWORD: ${{ secrets.ANDROID_SIGNING_PASSWORD }}
-          MAVEN_USERNAME: ${{ secrets.ANDROID_MAVEN_CENTRAL_USERNAME }}
-          MAVEN_PASSWORD: ${{ secrets.ANDROID_MAVEN_CENTRAL_PASSWORD }}
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.github/workflows/main_branch.yml

@@ -0,0 +1,21 @@
+name: Main branch
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      # actions/checkout can't be included in the composite setup action, because the composite
+      # action needs to be first checked out by the checkout action.
+      - name: Check out code
+        uses: actions/checkout@v5
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Preflight checks
+        uses: ./.github/actions/basic-preflight-check

.github/workflows/pull_request.yml

@@ -0,0 +1,22 @@
+name: Pull request
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+
+jobs:
+  pull_request:
+    runs-on: ubuntu-latest
+    steps:
+      # actions/checkout can't be included in the composite setup action, because the composite
+      # action needs to be first checked out by the checkout action.
+      - name: Check out code
+        uses: actions/checkout@v5
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Preflight checks
+        uses: ./.github/actions/basic-preflight-check

.gitignore

@@ -31,3 +31,6 @@ google-services.json
 
 # Android Profiling
 *.hprof
+
+# Kotlin
+.kotlin

CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+### annotations
+### framework
+### paparazzi
+
+
+
+## BOM [2.0.0-paparazzialpha02] - 2025-09-16
+Major breaking release that brings following changes:
+- Versioning of the library was completely changed. There are no longer Compose and Paparazzi
+suffixes in the artifact versions and clients are not forced to specify dependencies explicitly
+(unless it is required by the basic setup itself as described in README).
+- Library now releases BOM version that should be used instead of particular artifact versions.
+- This release depends on the unstable alpha version of the Paparazzi library, because newest stable
+version is no longer compatible with the newest Gradle versions. This is related only to `paparazzi`
+artifact and BOM, which explicitly reflects this `paparazzi` versioning in its version as well.
+Unstable Paparazzi library is reflected in the version name by `-paparazzialphaxx` suffix, which 
+matches the current alpha suffix version of the Paparazzi. Once Paparazzi releases stable version 
+and Ackee Snapshots update to it, the suffix will be removed. The base semantic version `x.x.x` of 
+the library version reflects just the version of Ackee Snapshots itself, independently on Paparazzi
+or any other dependency.
+- Update dependencies, including Kotlin to 2.2.20 and Kotest to 6.0.3.
+
+### paparazzi
+- Paparazzi version increased to `2.0.0-alpha02`. Make sure you use at least this version for
+Paparazzi Gradle plugin.

CONTRIBUTING.MD

@@ -0,0 +1,8 @@
+# CONTRIBUTING
+If you have something useful that could be added to the library or you found some bug, 
+feel free to open a PR.
+
+## PR
+Before submitting a PR, please make sure that:
+- You added tests that cover your changes if possible.
+- You ran `./gradlew preMergeRequestCheck` preflight checks and all passed.

README.md

@@ -3,7 +3,7 @@
 # Ackee Android Snapshots
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![Maven Central](https://img.shields.io/maven-central/v/io.github.ackeecz/snapshots-annotations)](https://central.sonatype.com/artifact/io.github.ackeecz/snapshots-annotations)
+[![Maven Central](https://img.shields.io/maven-central/v/io.github.ackeecz/snapshots-bom)](https://central.sonatype.com/artifact/io.github.ackeecz/snapshots-bom)
 
 ## Overview
 
@@ -14,9 +14,9 @@ components. It leverages Paparazzi for rendering snapshots, Showkase for compone
 
 The framework is designed with extensibility in mind, using a modular architecture:
 
+- `annotations` module contains shared code for preview annotations
 - `framework` module defines the base interfaces (`SnapshotEngine`, `SnapshotStrategy`) and common testing infrastructure
 - `paparazzi` module provides a concrete implementation of the snapshot engine using Paparazzi
-- `annotations` module contains shared code for preview annotations
 - Additional snapshot engine implementations can be added by implementing the `SnapshotEngine` interface
 
 ## Features
@@ -34,86 +34,70 @@ The framework is designed with extensibility in mind, using a modular architectu
 
 ## Installation
 
-Add the following dependencies to your `libs.versions.toml`:
+Add the following configuration, depending on what you need. You should always use BOM to be sure to
+get binary compatible dependencies. If you have a custom snapshots engine, you will need only 
+`annotations` and `framework` dependencies. Additionally, you can add `paparazzi` as well for our 
+Paparazzi engine implementation.
+
+### Annotations & Framework
+For `annotations` and `framework` artifacts you will need the following configuration:
 
 ```toml
 [versions]
-ackee-snapshots-annotations = "SPECIFY_VERSION"
-ackee-snapshots-framework = "SPECIFY_VERSION"
-ackee-snapshots-paparazzi = "SPECIFY_VERSION"
-compose-bom = "SPECIFY_VERSION"
+ackee-snapshots-bom = "SPECIFY_VERSION"
 showkase = "SPECIFY_VERSION"
-paparazzi = "SPECIFY_VERSION"
 
 [dependencies]
-ackee-snapshots-framework = { group = "io.github.ackeecz", name = "snapshots-framework", version.ref = "ackee-snapshots-framework" }
-ackee-snapshots-paparazzi = { group = "io.github.ackeecz", name = "snapshots-paparazzi", version.ref = "ackee-snapshots-paparazzi" }
-ackee-snapshots-annotations = { group = "io.github.ackeecz", name = "snapshots-annotations", version.ref = "ackee-snapshots-annotations" }
+ackee-snapshots-bom = { group = "io.github.ackeecz", name = "snapshots-bom", version.ref = "ackee-snapshots-bom" }
+ackee-snapshots-annotations = { group = "io.github.ackeecz", name = "snapshots-annotations" }
+ackee-snapshots-framework = { group = "io.github.ackeecz", name = "snapshots-framework" }
 
-# Required dependencies - versions need to be specified by the consumer
-androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version = "compose-bom" }
+# Showcase is needed for annotating previews and passing a selected PreviewSnapshotStrategy
 showkase-core = { module = "com.airbnb.android:showkase", version.ref = "showkase" }
 showkase-processor = { module = "com.airbnb.android:showkase-processor", version.ref = "showkase" }
-
-[plugins]
-paparazzi = { id = "app.cash.paparazzi", version.ref = "paparazzi" }
-```
-
-Apply the Paparazzi Gradle plugin in your app's `build.gradle.kts`:
-
-```kotlin
-plugins {
-    id("app.cash.paparazzi")
-}
 ```
 
 and specify dependencies
 
 ```kotlin
+implementation(platform(libs.ackee.snapshots.bom))
 implementation(libs.ackee.snapshots.annotations)
+testImplementation(libs.ackee.snapshots.framework)
+
 implementation(libs.showkase.core)
 ksp(libs.showkase.processor)
-
-testImplementation(libs.ackee.snapshots.framework)
-testImplementation(libs.ackee.snapshots.paparazzi)
 ```
 
-## Versioning
+### Paparazzi
+If you use `paparazzi` artifact, you will need the following additional configuration:
 
-The library uses a versioning scheme that reflects compatibility with its core dependencies:
+```toml
+[versions]
+# Ensure that this version is equal or greater than Paparazzi version in this project. Otherwise
+# there might be incompatibility between Paparazzi runtime used in Ackee Snapshots and Paparazzi
+# Gradle plugin used by your app.
+paparazzi = "SPECIFY_VERSION"
 
-### Framework Module
+[dependencies]
+ackee-snapshots-paparazzi = { group = "io.github.ackeecz", name = "snapshots-paparazzi" }
 
-The framework module version includes the Compose BOM version as a suffix:
-```
-{base_version}-{compose_bom_version}
+[plugins]
+paparazzi = { id = "app.cash.paparazzi", version.ref = "paparazzi" }
 ```
 
-Example: `0.1.0-2024.02.00`
+Apply the Paparazzi Gradle plugin in your module's `build.gradle.kts`:
 
-### Paparazzi Module
-The Paparazzi module version includes the Paparazzi version as a suffix:
-```
-{base_version}-{paparazzi_version}
+```kotlin
+plugins {
+    id(libs.plugins.paparazzi)
+}
 ```
 
-Example: `0.1.0-1.3.1`
-
-### Annotations Module
+and specify dependencies
 
-The annotations module uses only the base version without any suffix:
-```
-{base_version}
+```kotlin
+testImplementation(libs.ackee.snapshots.paparazzi)
 ```
-Example: `0.1.0`
-
-This versioning strategy helps users:
-- Track compatibility with specific Compose and Paparazzi versions
-- Choose the right artifact version for their setup
-- Avoid version conflicts with their project's dependencies
-
-Note: The library intentionally does not set Compose or Paparazzi versions to prevent version conflicts. You need to specify these versions in your
-project to ensure compatibility with your setup.
 
 ## Configuration
 
@@ -320,6 +304,7 @@ This setup will:
 
 ## Project Structure
 
+- **bom**: BOM module
 - **annotations**: Shared code for preview annotations. Used in test and production source sets.
 - **framework**: Core framework and testing infrastructure
 - **paparazzi**: Paparazzi integration for snapshot generation
@@ -352,7 +337,6 @@ To verify that your UI components haven't changed unexpectedly, run:
 If there are any differences between the recorded and current snapshots, the test will fail and Paparazzi will generate a report showing the
 differences.
 
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.