Merge branch 'main' into renovate/kotlin-monorepo

Author: mrmans0n

.github/workflows/preview-docs.yaml

@@ -0,0 +1,41 @@
+name: Preview documentation
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements.txt'
+      - 'pyproject.toml'
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  preview_docs:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    env:
+      TERM: dumb
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup uv
+        if: github.event.action != 'closed'
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        if: github.event.action != 'closed'
+        run: uv sync --frozen
+
+      - name: Build documentation
+        if: github.event.action != 'closed'
+        run: uv run mkdocs build
+
+      - name: Deploy PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./site/

.github/workflows/publish-docs.yaml

@@ -7,6 +7,10 @@ on:
     tags:
       - v*
 
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
 jobs:
   deploy_docs:
     if: github.repository == 'mrmans0n/compose-rules'
@@ -16,24 +20,46 @@ jobs:
 
     steps:
       - uses: actions/checkout@v6
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
 
       - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Configure Git
         run: |
-          python3 -m pip install --upgrade pip
-          python3 -m pip install mkdocs
-          python3 -m pip install mkdocs-material
-          python3 -m pip install mdx_truly_sane_lists
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Build site
-        run: mkdocs build
+      - name: Fetch gh-pages branch
+        run: git fetch origin gh-pages:gh-pages || true
 
-      - name: Deploy docs
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
+      - name: Determine version
+        id: version
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+            # Extract version from tag (remove 'v' prefix)
+            VERSION="${GITHUB_REF#refs/tags/v}"
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+            echo "alias=latest" >> $GITHUB_OUTPUT
+            echo "is_stable=true" >> $GITHUB_OUTPUT
+          else
+            # Main branch = next/development version
+            echo "version=next" >> $GITHUB_OUTPUT
+            echo "alias=" >> $GITHUB_OUTPUT
+            echo "is_stable=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Deploy documentation (stable version)
+        if: steps.version.outputs.is_stable == 'true'
+        run: |
+          uv run mike deploy --push --update-aliases ${{ steps.version.outputs.version }} ${{ steps.version.outputs.alias }}
+          uv run mike set-default --push latest
+
+      - name: Deploy documentation (development version)
+        if: steps.version.outputs.is_stable == 'false'
+        run: |
+          uv run mike deploy --push ${{ steps.version.outputs.version }}

.github/workflows/update-release.yaml

@@ -53,3 +53,40 @@ jobs:
                 tag: v${{ env.VERSION }}
                 asset_name: detekt-compose-${{ env.VERSION }}-all.jar
                 overwrite: true
+
+          - name: Extract dependency versions and update release notes
+            if: success() && !endsWith(env.VERSION, '-SNAPSHOT')
+            env:
+                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            run: |
+                # Parse versions from libs.versions.toml (match only version strings, not plugin definitions)
+                DETEKT_VERSION=$(grep '^detekt = "' gradle/libs.versions.toml | sed 's/detekt = "\([^"]*\)".*/\1/')
+                KOTLIN_DETEKT_VERSION=$(grep '^kotlin-detekt = "' gradle/libs.versions.toml | sed 's/kotlin-detekt = "\([^"]*\)".*/\1/')
+                KTLINT_VERSION=$(grep '^ktlint = "' gradle/libs.versions.toml | sed 's/ktlint = "\([^"]*\)".*/\1/')
+                KOTLIN_KTLINT_VERSION=$(grep '^kotlin-ktlint = "' gradle/libs.versions.toml | sed 's/kotlin-ktlint = "\([^"]*\)".*/\1/')
+
+                echo "Detekt: $DETEKT_VERSION (Kotlin $KOTLIN_DETEKT_VERSION)"
+                echo "Ktlint: $KTLINT_VERSION (Kotlin $KOTLIN_KTLINT_VERSION)"
+
+                # Get current release body
+                RELEASE_ID=$(gh api repos/${{ github.repository }}/releases/tags/v${{ env.VERSION }} --jq '.id')
+                CURRENT_BODY=$(gh api repos/${{ github.repository }}/releases/$RELEASE_ID --jq '.body')
+
+                # Check if dependency matrix already exists in the body
+                if echo "$CURRENT_BODY" | grep -q "## Dependency Matrix"; then
+                    echo "Dependency matrix already exists, skipping update"
+                    exit 0
+                fi
+
+                # Create the dependency matrix table (using printf for proper newlines)
+                DEPENDENCY_TABLE=$(printf "## Dependency Matrix\n\n| version | kotlin version |\n| ------- | -------------- |\n| detekt %s | %s |\n| ktlint %s | %s |" "$DETEKT_VERSION" "$KOTLIN_DETEKT_VERSION" "$KTLINT_VERSION" "$KOTLIN_KTLINT_VERSION")
+
+                # Append the dependency matrix to the release body
+                NEW_BODY=$(printf "%s\n\n%s" "$CURRENT_BODY" "$DEPENDENCY_TABLE")
+
+                # Update the release
+                gh api repos/${{ github.repository }}/releases/$RELEASE_ID \
+                    -X PATCH \
+                    -f body="$NEW_BODY"
+
+                echo "Release notes updated with dependency matrix"

.gitignore

@@ -38,5 +38,8 @@ google-services.json
 # MkDocs site
 site/
 
+# Python virtual environment
+.venv/
+
 # Fleet
 **/.fleet/settings.json

RELEASING.md

@@ -13,6 +13,8 @@
    1. Make sure the release name and the tags associated to it match. If not, you make them match.
    2. Publish the draft of the release.
 
+   This will trigger a GitHub Action workflow that will publish the versioned documentation for this release.
+
 4. Update the `VERSION_NAME` in `gradle.properties` to the next SNAPSHOT version by adding `-SNAPSHOT` to the version.
 5. Commit and push to main
 
@@ -21,3 +23,29 @@
    $ git push
    ```
 6. You're done! 🎉
+
+## Documentation Versioning
+
+The documentation is automatically versioned using [mike](https://github.com/jimporter/mike):
+
+- **Stable versions**: When a release tag (e.g., `v0.5.0`) is pushed, the documentation is deployed as a versioned site
+  and the `latest` alias is updated to point to this version.
+- **Development version**: Commits to `main` branch update the `next` version, which represents the unreleased
+  development documentation.
+- **Default version**: The documentation site defaults to `latest`, which always points to the most recent stable
+  release.
+
+### Working with documentation locally
+
+To preview the documentation with versioning locally:
+
+```bash
+# Install dependencies (first time only)
+uv sync
+
+# Serve the current docs (without versioning)
+uv run mkdocs serve
+
+# Or use mike to preview versioned docs
+uv run mike serve
+```

docs/README.md

@@ -0,0 +1,113 @@
+# Compose Rules Documentation
+
+This directory contains the source documentation for Compose Rules, which is built
+using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/).
+
+## Documentation Structure
+
+- `index.md` - Overview and introduction
+- `ktlint.md` - Guide for using Compose Rules with ktlint
+- `detekt.md` - Guide for using Compose Rules with detekt
+- `rules.md` - Comprehensive list of all rules with examples
+
+## Versioning
+
+The documentation is **versioned** using [mike](https://github.com/jimporter/mike):
+
+- **Stable versions** (e.g., `0.5.0`, `0.4.0`) - Created automatically when a release tag is pushed
+- **Development version** (`next`) - Updated automatically on every push to `main` branch
+- **Default version** (`latest`) - Always points to the most recent stable release
+
+### Viewing Different Versions
+
+Visit the [documentation site](https://mrmans0n.github.io/compose-rules/) and use the version selector in the header to
+switch between:
+
+- Latest stable version (default)
+- Specific release versions
+- Next (development) version
+
+## Local Development
+
+### Quick Preview (Recommended)
+
+For fast iteration when writing documentation:
+
+```bash
+# Install dependencies (first time only)
+uv sync
+
+# Serve the docs locally
+uv run mkdocs serve
+```
+
+Visit `http://localhost:8000` to see your changes live. This serves the current docs without versioning.
+
+### Preview with Versioning
+
+To see how the documentation will look with the version selector:
+
+```bash
+# Deploy a test version locally (won't push to GitHub)
+uv run mike deploy dev --no-push
+
+# Serve with version selector
+uv run mike serve
+```
+
+Visit `http://localhost:8000` to see the versioned site.
+
+## Making Changes
+
+1. Edit the relevant `.md` files in this directory
+2. Preview your changes locally with `mkdocs serve`
+3. Commit and push to a feature branch
+4. Create a pull request
+
+When your PR is merged to `main`:
+
+- The `next` version of the docs will be automatically updated
+- Changes will be visible at `https://mrmans0n.github.io/compose-rules/next/`
+
+When a new release is created:
+
+- A new versioned documentation site is created automatically
+- The `latest` version is updated to point to the new release
+
+## Documentation Guidelines
+
+- Use clear, concise language
+- Include code examples where relevant
+- Link to related rules or sections when applicable
+- Test all code examples to ensure they work
+- Follow the existing documentation structure and style
+
+## Useful Commands
+
+```bash
+# Serve docs locally (fast, no versioning)
+uv run mkdocs serve
+
+# Build the docs (output in site/ directory)
+uv run mkdocs build
+
+# List all deployed versions
+uv run mike list
+
+# Preview versioned docs locally
+uv run mike serve
+```
+
+## Resources
+
+- [MkDocs Documentation](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+- [mike Documentation](https://github.com/jimporter/mike)
+- [Markdown Guide](https://www.markdownguide.org/)
+
+## Questions?
+
+If you have questions about the documentation:
+
+- Open an issue on GitHub
+- Reach out to the maintainers

docs/detekt.md

@@ -1,4 +1,4 @@
-When using the [detekt Gradle Plugin](https://detekt.dev/docs/gettingstarted/gradle), you can specify the dependency on this set of rules by using `detektPlugins`.
+Add the dependency using `detektPlugins` in your [detekt Gradle Plugin](https://detekt.dev/docs/gettingstarted/gradle) configuration:
 
 ```groovy
 dependencies {
@@ -21,17 +21,17 @@ Older version support can be found in the [release notes](https://github.com/mrm
 
 ## Using with detekt CLI / detekt IDE plugin
 
-The [releases](https://github.com/mrmans0n/compose-rules/releases) page contains an [uber jar](https://stackoverflow.com/questions/11947037/what-is-an-uber-jar) for each version release that can be used to run with the [CLI version of detekt](https://detekt.dev/docs/gettingstarted/cli).
+The [releases](https://github.com/mrmans0n/compose-rules/releases) page contains an [uber jar](https://stackoverflow.com/questions/11947037/what-is-an-uber-jar) for each version that can be used with the [detekt CLI](https://detekt.dev/docs/gettingstarted/cli):
 
 ```shell
 detekt -p detekt-compose-<VERSION>-all.jar -c your/config/detekt.yml
 ```
 
-For the IDE plugin, you'll need to add the uber jar to the list of custom plugins in its configuration, and don't forget to also enable the rules in the yml config provided to the plugin for it to work.
+For the IDE plugin, add the uber jar to the custom plugins list and enable the rules in the yml config.
 
 ## Enabling rules
 
-For the rules to be picked up, you will need to enable them in your `detekt.yml` configuration file.
+Enable the rules in your `detekt.yml` configuration file:
 
 ```yaml
 Compose:
@@ -166,9 +166,7 @@ Compose:
 
 ## Disabling a specific rule
 
-To disable a rule you have to follow the [instructions from the detekt documentation](https://detekt.dev/docs/introduction/suppressing-rules), and use the id of the rule you want to disable.
-
-For example, to disable `ComposableNaming` in a particular method, you can suppress it.
+Follow the [detekt documentation](https://detekt.dev/docs/introduction/suppressing-rules) to suppress specific rules. For example:
 
 ```kotlin
 @Suppress("ComposableNaming")

docs/index.md

@@ -1,27 +1,17 @@
-The Compose Rules is a set of custom Ktlint / Detekt rules to ensure that your composables don't fall into common pitfalls, that might be easy to miss in code reviews.
+Compose Rules is a set of custom ktlint / detekt rules to ensure that your composables don't fall into common pitfalls that might be easy to miss in code reviews.
 
 ## Why
-It can be challenging for big teams to start adopting Compose, particularly because not everyone will start at same time or with the same patterns. We tried to ease the pain by creating a set of Compose static checks.
 
-Compose has lots of superpowers but also has a bunch of footguns to be aware of [as seen in this Twitter Thread](https://twitter.com/mrmans0n/status/1507390768796909571).
+It can be challenging for big teams to adopt Compose, particularly because not everyone starts at the same time or with the same patterns. We created these static checks to ease that pain.
 
-This is where our static checks come in. We want to detect as many potential issues as we can, as quickly as we can. In this case we want an error to show prior to engineers having to review code. Similar to other static check libraries we hope this leads to a "don't shoot the messengers" philosphy which will foster healthy Compose adoption.
+Compose has lots of superpowers but also has a bunch of footguns to be aware of, [as seen in this Twitter thread](https://twitter.com/mrmans0n/status/1507390768796909571).
+
+This is where static checks come in. We want to detect as many potential issues as possible, as early as possible—ideally before code review. Similar to other static analysis libraries, we hope this fosters a "don't shoot the messenger" philosophy and healthy Compose adoption.
 
 ## Using with ktlint
 
 You can refer to the [Using with ktlint](https://mrmans0n.github.io/compose-rules/ktlint) documentation.
 
 ## Using with detekt
 
-You can refer to the [Using with detekt](https://mrmans0n.github.io/compose-rules/detekt) documentation.
-
-## Migrating from Twitter Compose Rules
-
-The process to migrate to these rules coming from the Twitter ones is simple.
-
-1. Change the project coordinates in your gradle build scripts
-   2. For detekt, `com.twitter.compose.rules:detekt:$version` becomes `io.nlopez.compose.rules:detekt:$version`
-   3. For ktlint, `com.twitter.compose.rules:ktlint:$version` becomes `io.nlopez.compose.rules:ktlint:$version`
-4. Update `$version` to the latest: ![Latest version](https://img.shields.io/maven-central/v/io.nlopez.compose.rules/ktlint) - see the project [releases page](https://github.com/mrmans0n/compose-rules/releases).
-5. **If you are using Detekt**: update the config file (e.g. `detekt.yml`) so that the rule set name `TwitterCompose` becomes `Compose`. Keep in mind that there are a lot of new rules in this repo that weren't in Twitter's, so you'd be better copying over from the [example configuration](https://mrmans0n.github.io/compose-rules/detekt).
-6. Done!
+You can refer to the [Using with detekt](https://mrmans0n.github.io/compose-rules/detekt) documentation.