From b5c67bf8d2af09242379dbff43dee6ed8150f179 Mon Sep 17 00:00:00 2001 From: Goooler Date: Thu, 28 May 2026 14:39:20 +0800 Subject: [PATCH 1/5] Update formatting commands in CONTRIBUTING.md to use spotlessApply --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 175703264..40ddca05c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ Thank you for considering contributing to the Shadow Gradle plugin! This documen Shadow uses [Spotless](https://github.com/diffplug/spotless) to maintain consistent code formatting. - **Check code style**: `./gradlew spotlessCheck` -- **Format code**: `./gradlew spotlessFormat` +- **Format code**: `./gradlew spotlessApply` Please ensure your code is properly formatted before submitting a pull request. @@ -62,7 +62,7 @@ When adding new features or public APIs: ### Before Submitting a Pull Request -1. Run `./gradlew spotlessFormat` to format your code +1. Run `./gradlew spotlessApply` to format your code 2. Run `./gradlew spotlessCheck` to verify formatting 3. Run all test suites: `./gradlew test documentTest functionalTest` 4. Run `./gradlew checkKotlinAbi` to ensure API compatibility @@ -70,4 +70,3 @@ When adding new features or public APIs: 6. Optionally, run `./gradlew build` to run compilation, tests, and standard verification tasks configured for the project 7. Ensure your commit messages are clear and descriptive 8. Update the `Unreleased` section in [CHANGELOG](docs/changes/README.md) if applicable - From 27e3728a3f31a1adcfe4217a4fec96e366fb8f94 Mon Sep 17 00:00:00 2001 From: Goooler Date: Thu, 28 May 2026 14:40:51 +0800 Subject: [PATCH 2/5] Refactor contributing guidelines to consolidate code formatting commands --- CONTRIBUTING.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40ddca05c..99bf44a45 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,8 +8,7 @@ Thank you for considering contributing to the Shadow Gradle plugin! This documen Shadow uses [Spotless](https://github.com/diffplug/spotless) to maintain consistent code formatting. -- **Check code style**: `./gradlew spotlessCheck` -- **Format code**: `./gradlew spotlessApply` +- **Check and format code**: `./gradlew spotlessApply` Please ensure your code is properly formatted before submitting a pull request. @@ -62,11 +61,10 @@ When adding new features or public APIs: ### Before Submitting a Pull Request -1. Run `./gradlew spotlessApply` to format your code -2. Run `./gradlew spotlessCheck` to verify formatting -3. Run all test suites: `./gradlew test documentTest functionalTest` -4. Run `./gradlew checkKotlinAbi` to ensure API compatibility -5. Run `./gradlew lint` to check for potential issues -6. Optionally, run `./gradlew build` to run compilation, tests, and standard verification tasks configured for the project -7. Ensure your commit messages are clear and descriptive -8. Update the `Unreleased` section in [CHANGELOG](docs/changes/README.md) if applicable +1. Run `./gradlew spotlessApply` to check and format your code +2. Run all test suites: `./gradlew test documentTest functionalTest` +3. Run `./gradlew checkKotlinAbi` to ensure API compatibility +4. Run `./gradlew lint` to check for potential issues +5. Optionally, run `./gradlew build` to run compilation, tests, and standard verification tasks configured for the project +6. Ensure your commit messages are clear and descriptive +7. Update the `Unreleased` section in [CHANGELOG](docs/changes/README.md) if applicable From c3a4d0c9a2612301053085b6d31476480baaa19d Mon Sep 17 00:00:00 2001 From: Goooler Date: Thu, 28 May 2026 14:51:31 +0800 Subject: [PATCH 3/5] Improve CONTRIBUTING.md with prerequisites, testing tips, ABI files, and MkDocs preview --- CONTRIBUTING.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99bf44a45..9c9162469 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,11 @@ Thank you for considering contributing to the Shadow Gradle plugin! This document provides guidelines and information to help you get started. +## Prerequisites + +- **Java Development Kit (JDK)**: JDK 17 or higher is required to build the project. JDK 25 is recommended (and is used in GitHub Actions). +- **Gradle**: The project uses the Gradle Wrapper, so you do not need to install Gradle globally. Run command-line tasks using `./gradlew` (or `gradlew.bat` on Windows). + ## Development Commands ### Code Style @@ -17,19 +22,25 @@ Please ensure your code is properly formatted before submitting a pull request. Shadow has multiple test suites to ensure code quality: - **Unit tests**: `./gradlew test` -- **Documentation tests**: `./gradlew documentTest` - Tests code snippets in the `./docs` directory +- **Documentation tests**: `./gradlew documentTest` - Tests code snippets in the `docs/` directory - **Functional/Integration tests**: `./gradlew functionalTest` +#### Running Specific Tests + +To speed up local development, you can run specific test classes or methods: +- Run a specific unit test: `./gradlew test --tests "com.example.YourTestClass"` +- Run functional tests against a specific Gradle version: `./gradlew functionalTest -PtestGradleVersion=9.1.0` (useful to verify compatibility locally with the minimum or a custom Gradle version) + Make sure all tests pass before submitting your changes. ### API Compatibility -Shadow uses Kotlin's [binary compatibility validator](https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html) to track public API changes. +Shadow uses Kotlin's built-in ABI validator to track public API changes. - **Check API dumps**: `./gradlew checkKotlinAbi` - **Update API dumps**: `./gradlew updateKotlinAbi` -If you add or modify public APIs, you'll need to update the API dump files. +API dump files are located under the `api/` directory (e.g., [shadow.api](api/shadow.api)). If you add or modify public APIs, you'll need to run `./gradlew updateKotlinAbi` to update the API dump files and include the updated dump files in your pull request. ### Linting @@ -38,6 +49,14 @@ Shadow uses [Android Lint](https://developer.android.com/studio/write/lint) to c - **Run lint checks**: `./gradlew lint` - **Update lint baseline**: `./gradlew updateLintBaseline` +### Documentation Preview + +Shadow's user guide is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). You can build and preview the documentation website locally: + +- **Install MkDocs dependencies**: `pip install mkdocs mkdocs-material` +- **Preview documentation locally**: `mkdocs serve` (then navigate to `http://127.0.0.1:8000/`) +- **Build the static site**: `mkdocs build` + ## Contribution Guidelines ### Fixing Issues @@ -61,7 +80,7 @@ When adding new features or public APIs: ### Before Submitting a Pull Request -1. Run `./gradlew spotlessApply` to check and format your code +1. Run `./gradlew spotlessApply` to format your code 2. Run all test suites: `./gradlew test documentTest functionalTest` 3. Run `./gradlew checkKotlinAbi` to ensure API compatibility 4. Run `./gradlew lint` to check for potential issues From 21e8ed592e4a448d62844c35b927de29c6e8fa43 Mon Sep 17 00:00:00 2001 From: Goooler Date: Thu, 28 May 2026 14:52:56 +0800 Subject: [PATCH 4/5] Reformat --- CONTRIBUTING.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c9162469..486a62340 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,14 @@ # Contributing to Shadow -Thank you for considering contributing to the Shadow Gradle plugin! This document provides guidelines and information to help you get started. +Thank you for considering contributing to the Shadow Gradle plugin! This document provides guidelines and information to +help you get started. ## Prerequisites -- **Java Development Kit (JDK)**: JDK 17 or higher is required to build the project. JDK 25 is recommended (and is used in GitHub Actions). -- **Gradle**: The project uses the Gradle Wrapper, so you do not need to install Gradle globally. Run command-line tasks using `./gradlew` (or `gradlew.bat` on Windows). +- **Java Development Kit (JDK)**: JDK 17 or higher is required to build the project. JDK 25 is recommended (and is used + in GitHub Actions). +- **Gradle**: The project uses the Gradle Wrapper, so you do not need to install Gradle globally. Run command-line tasks + using `./gradlew` (or `gradlew.bat` on Windows). ## Development Commands @@ -28,8 +31,10 @@ Shadow has multiple test suites to ensure code quality: #### Running Specific Tests To speed up local development, you can run specific test classes or methods: + - Run a specific unit test: `./gradlew test --tests "com.example.YourTestClass"` -- Run functional tests against a specific Gradle version: `./gradlew functionalTest -PtestGradleVersion=9.1.0` (useful to verify compatibility locally with the minimum or a custom Gradle version) +- Run functional tests against a specific Gradle version: `./gradlew functionalTest -PtestGradleVersion=9.1.0` (useful + to verify compatibility locally with the minimum or a custom Gradle version) Make sure all tests pass before submitting your changes. @@ -40,7 +45,9 @@ Shadow uses Kotlin's built-in ABI validator to track public API changes. - **Check API dumps**: `./gradlew checkKotlinAbi` - **Update API dumps**: `./gradlew updateKotlinAbi` -API dump files are located under the `api/` directory (e.g., [shadow.api](api/shadow.api)). If you add or modify public APIs, you'll need to run `./gradlew updateKotlinAbi` to update the API dump files and include the updated dump files in your pull request. +API dump files are located under the `api/` directory (e.g., [shadow.api](api/shadow.api)). If you add or modify public +APIs, you'll need to run `./gradlew updateKotlinAbi` to update the API dump files and include the updated dump files in +your pull request. ### Linting @@ -51,7 +58,8 @@ Shadow uses [Android Lint](https://developer.android.com/studio/write/lint) to c ### Documentation Preview -Shadow's user guide is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). You can build and preview the documentation website locally: +Shadow's user guide is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). You can build and +preview the documentation website locally: - **Install MkDocs dependencies**: `pip install mkdocs mkdocs-material` - **Preview documentation locally**: `mkdocs serve` (then navigate to `http://127.0.0.1:8000/`) @@ -84,6 +92,7 @@ When adding new features or public APIs: 2. Run all test suites: `./gradlew test documentTest functionalTest` 3. Run `./gradlew checkKotlinAbi` to ensure API compatibility 4. Run `./gradlew lint` to check for potential issues -5. Optionally, run `./gradlew build` to run compilation, tests, and standard verification tasks configured for the project +5. Optionally, run `./gradlew build` to run compilation, tests, and standard verification tasks configured for the + project 6. Ensure your commit messages are clear and descriptive 7. Update the `Unreleased` section in [CHANGELOG](docs/changes/README.md) if applicable From e44b1a13584bbdaec01b7c2fc2f97541b6736bab Mon Sep 17 00:00:00 2001 From: Zongle Wang Date: Thu, 28 May 2026 14:55:32 +0800 Subject: [PATCH 5/5] Update JDK requirements in CONTRIBUTING.md Removed mention of JDK 25 usage in GitHub Actions. --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 486a62340..30b5f19a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,7 @@ help you get started. ## Prerequisites -- **Java Development Kit (JDK)**: JDK 17 or higher is required to build the project. JDK 25 is recommended (and is used - in GitHub Actions). +- **Java Development Kit (JDK)**: JDK 17 or higher is required to build the project. JDK 25 is recommended. - **Gradle**: The project uses the Gradle Wrapper, so you do not need to install Gradle globally. Run command-line tasks using `./gradlew` (or `gradlew.bat` on Windows).