Merge remote-tracking branch 'origin/main' into g/20250311/kotlin-new-app-block

// Conflicts:
//	src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/KmpPluginTest.kt

Author: Goooler

.gitattributes

@@ -1,4 +1,5 @@
 * text=auto eol=lf
 
-gradlew binary
-gradlew.bat binary
+*.bat text eol=crlf
+*.jar binary
+*.svg binary

.github/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing to Shadow Gradle Plugin
+
+Thank you for considering contributing

.github/actions/deploy-site/action.yml

@@ -4,12 +4,19 @@ description: 'Deploy site to GitHub Pages'
 runs:
   using: 'composite'
   steps:
-    - name: Deploy Site
+    - uses: gradle/actions/setup-gradle@v4
+      with:
+        cache-read-only: true
+    - name: Prepare API documentation
+      shell: bash
+      run: ./gradlew dokkaHtml --no-configuration-cache
+    - name: Build Site
       shell: bash
       run: |
-        git config --global user.name 'github-actions[bot]'
-        git config --global user.email 'github-actions[bot]@users.noreply.github.com'
         # Don't cache it to track updates.
         pip install mkdocs-material
-        # Incremental pushes, make sure gh-pages branch is fetched by checkout.
-        mkdocs gh-deploy
+        mkdocs build
+    - uses: actions/upload-pages-artifact@v3
+      with:
+        path: site
+    - uses: actions/deploy-pages@v4

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
   publish-snapshot:
     needs: build
     runs-on: ubuntu-latest
-    if: github.repository == 'GradleUp/shadow' && github.ref == 'refs/heads/main'
+    if: github.event.repository.fork == false && github.ref == 'refs/heads/main'
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4

.github/workflows/deploy.yml

@@ -6,12 +6,13 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    if: github.repository == 'GradleUp/shadow'
+    if: github.event.repository.fork == false
+    environment:
+      name: github-pages
     permissions:
       contents: write
+      id-token: write
+      pages: write
     steps:
       - uses: actions/checkout@v4
-        with:
-          # Fetch all tags and branches, so that MkDocs could push incremental updates.
-          fetch-depth: 0
       - uses: ./.github/actions/deploy-site

.github/workflows/release.yml

@@ -8,14 +8,15 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
-    if: github.repository == 'GradleUp/shadow'
+    if: github.event.repository.fork == false
+    environment:
+      name: github-pages
     permissions:
       contents: write
+      id-token: write
+      pages: write
     steps:
       - uses: actions/checkout@v4
-        with:
-          # Fetch all tags and branches, so that MkDocs could push incremental updates.
-          fetch-depth: 0
       - uses: actions/setup-java@v4
         with:
           distribution: 'zulu'
@@ -24,7 +25,7 @@ jobs:
         with:
           cache-read-only: true
       # Disable CC due to https://github.com/gradle/gradle/issues/22779
-      - run: ./gradlew publish publishPlugins dokkaHtml --no-configuration-cache
+      - run: ./gradlew publish publishPlugins --no-configuration-cache
         env:
           GRADLE_PUBLISH_KEY: ${{ secrets.GRADLE_KEY }}
           GRADLE_PUBLISH_SECRET: ${{ secrets.GRADLE_SECRET }}

.idea/icon.svg

@@ -1,16 +1,59 @@
 <div style="text-align: center;">
-  <img src="images/logo.svg" alt="Shadow Gradle Plugin" style="max-width: 300px; height: auto;">
+  <img src="images/logo.svg" alt="Shadow Gradle Plugin" width="300"/>
   <h1><strong>Shadow Gradle Plugin</strong></h1>
-  <p><em>The library author's dependency toolkit</em></p>
 </div>
 
----
+# Introduction
 
-Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the ID [
-`com.github.johnrengelman.shadow`](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
-before maintenance was transferred to the [GradleUp organization](https://github.com/GradleUp) to ensure future
-development, see [#908](https://github.com/GradleUp/shadow/issues/908).
+Shadow is a Gradle plugin for combining a project's dependency classes and resources into a single
+output Jar.
+The combined Jar is often referred to a _fat-jar_ or _uber-jar_.
+Shadow utilizes [`JarInputStream`](https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarInputStream.html) and [`JarOutputStream`](https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarOutputStream.html) to efficiently process dependent libraries
+into the output jar without incurring the I/O overhead of expanding the jars to disk.
 
-If you are still using the old plugin ID in your build script, we recommend to switch to the new plugin ID [
-`com.gradleup.shadow`](https://plugins.gradle.org/plugin/com.gradleup.shadow)
-and update to the latest version to receive all the latest bug fixes and improvements.
+!!! warning "Plugin ID Change"
+
+    Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the ID [
+    `com.github.johnrengelman.shadow`](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
+    before maintenance was transferred to the [GradleUp organization](https://github.com/GradleUp) to ensure future
+    development, see [#908](https://github.com/GradleUp/shadow/issues/908).
+    
+    If you are still using the old plugin ID in your build script, we recommend to switch to the new plugin ID [
+    `com.gradleup.shadow`](https://plugins.gradle.org/plugin/com.gradleup.shadow)
+    and update to the latest version to receive all the latest bug fixes and improvements.
+
+## Benefits of Shadow
+
+Shadowing a project output has 2 major use cases:
+
+1. Creating an _executable_ JAR distribution
+2. Bundling and relocating common dependencies in libraries to avoid classpath conflicts
+
+### Executable Distributions
+
+Executable distribution is the main use case for deploying an _application_ that can be executed/run in the runtime
+environment.
+In the case of Shadow, this is a single _uber_ or _fat_ JAR.
+The JAR file contains all the application code and dependent libraries to execute (not including the standard JVM
+libraries).
+The shadow JAR does **not** include the JRE itself.
+It must be available on the target system.
+
+Executable JARs contain a JAR MANIFEST that specifies the application Main Class.
+This allows the application to be started with a single command:
+
+```shell
+java -jar application-shadow.jar
+```
+
+### Library Bundling
+
+Dependency bundling and relocation is the main use case for _library_ authors.
+The goal of a bundled library is to create a pre-packaged dependency for other libraries or applications to utilize.
+Often in these scenarios, a library may contain a dependency that a downstream library or application also uses.
+In _some_ cases, different versions of this common dependency can cause an issue in either the upstream library or
+the downstream application.
+These issues often manifest themselves as binary incompatibilities in either the library or application code.
+
+By utilizing Shadow's ability to _relocate_ the package names for dependencies, a library author can ensure that the
+library's dependencies will not conflict with the same dependency being declared by the downstream application.

NOTICE

@@ -1,13 +1,13 @@
 # About This Project
 
-I started this project in December 2012. We were working on converting from a monolithic application into the
+I (John Engelman) started this project in December 2012. We were working on converting from a monolithic application into the
 new hot jazz of "microservices" using Dropwizard.
 I had also just started learning about Gradle and I knew that the incremental build system it provided would benefit
 our development team greatly.
 Unfortunately, the closest thing that Gradle had to Maven's Shade plugin was its ability to create application TARs and
 ZIPs.
 
-So, Charlie Knudsen and I (John Engelman) set out to port the existing Shade code into a Gradle plugin.
+So, Charlie Knudsen and I set out to port the existing Shade code into a Gradle plugin.
 This port is what existed up until the `0.9` milestone releases for Shadow.
 It functioned, but it wasn't idiomatic Gradle by any means.
 
@@ -19,6 +19,7 @@ so Shadow was published there.
 ## Maintainers
 
 * [John Engelman](https://github.com/johnrengelman)
+* [Goooler](https://github.com/Goooler)
 
 ## Contributors