Polish CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,15 +1,21 @@
 # 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.
+- **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
 
 Shadow uses [Spotless](https://github.com/diffplug/spotless) to maintain consistent code formatting.
 
-- **Check code style**: `./gradlew spotlessCheck`
-- **Format code**: `./gradlew spotlessFormat`
+- **Check and format code**: `./gradlew spotlessApply`
 
 Please ensure your code is properly formatted before submitting a pull request.
 
@@ -18,19 +24,29 @@ 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
 
@@ -39,6 +55,15 @@ 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
@@ -62,12 +87,11 @@ When adding new features or public APIs:
 
 ### Before Submitting a Pull Request
 
-1. Run `./gradlew spotlessFormat` 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 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