Gradle Boilerplate Project

A comprehensive Gradle boilerplate template for Java/Kotlin projects with modern development practices, testing, and CI/CD integration.

🚀 Features

Modern Gradle Setup: Kotlin DSL configuration with Gradle 8.11.1
Java 17+ Support: Compatible with Java 17 and 21
Kotlin Integration: Ready for mixed Java/Kotlin projects
Testing Framework: JUnit 5, AssertJ, and Mockito
Code Quality: Checkstyle, PMD, SpotBugs integration
Code Coverage: JaCoCo for test coverage reporting
CI/CD Pipeline: GitHub Actions workflow
Multi-platform Testing: Tests on Ubuntu, Windows, and macOS
Dependency Management: Centralized dependency configuration
Documentation: Comprehensive README and inline documentation

📁 Project Structure

├── .github/
│   ├── workflows/
│   │   └── ci.yml                    # GitHub Actions CI/CD pipeline
│   └── copilot-instructions.md       # GitHub Copilot configuration
├── config/
│   ├── checkstyle/
│   │   └── checkstyle.xml           # Checkstyle configuration
│   ├── pmd/
│   │   └── ruleset.xml              # PMD rules
│   └── spotbugs/
│       └── exclude.xml              # SpotBugs exclusions
├── gradle/
│   └── wrapper/                     # Gradle wrapper files
├── src/
│   ├── main/java/                   # Main source code
│   └── test/java/                   # Test source code
├── build.gradle.kts                 # Gradle build script
├── gradlew                          # Gradle wrapper (Unix)
├── gradlew.bat                      # Gradle wrapper (Windows)
└── settings.gradle.kts              # Gradle settings

🛠️ Prerequisites

Java 17 or higher
Git

� Corporate Network Setup

Important: If you're working in a corporate environment with SSL inspection or proxies, you may encounter SSL certificate errors when first running Gradle. This is because the Gradle wrapper needs to download Gradle itself before it can read the gradle.properties configuration.

Quick Fix for Corporate Networks

Run the setup script:

# PowerShell (recommended)
.\setup-corporate-network.ps1

# Or Command Prompt
setup-corporate-network.bat

Manual alternative: Download Gradle manually from https://services.gradle.org/distributions/gradle-8.11.1-all.zip and extract to the project directory.
Complete guide: See CORPORATE-NETWORK-GUIDE.md for detailed troubleshooting.

Configuration Files

gradle.properties: Pre-configured with corporate network settings
setup-corporate-network.ps1: Automated setup script
CORPORATE-NETWORK-GUIDE.md: Comprehensive troubleshooting guide

🚦 Quick Start

For Standard Networks

Use this template: Click "Use this template" button on GitHub or clone the repository
Update project details: Modify package names, project name, and description
Run tests: ./gradlew test
Build project: ./gradlew build

For Corporate Networks

Follow corporate setup: See section above for SSL/proxy configuration
Run setup script: .\setup-corporate-network.ps1
Update project details: Same as standard networks
Build and test: Use provided scripts or manual Gradle download

📝 Available Gradle Tasks

Build Tasks

./gradlew build - Build the entire project
./gradlew cleanBuild - Clean and build the project
./gradlew run - Run the main application

Testing Tasks

./gradlew test - Run all tests
./gradlew jacocoTestReport - Generate test coverage report
./gradlew jacocoTestCoverageVerification - Verify coverage meets threshold

Code Quality Tasks

./gradlew codeQuality - Run all code quality checks
./gradlew checkstyleMain - Run Checkstyle on main sources
./gradlew pmdMain - Run PMD on main sources
./gradlew spotbugsMain - Run SpotBugs on main sources

🧪 Testing

The project uses JUnit 5 as the testing framework with:

AssertJ for fluent assertions
Mockito for mocking dependencies
Test coverage reporting with JaCoCo

Example test structure:

@Test
@DisplayName("Should return greeting message")
void shouldReturnGreetingMessage() {
    // Given
    App app = new App();
    
    // When
    String greeting = app.getGreeting();
    
    // Then
    assertThat(greeting).isEqualTo("Hello World!");
}

🔍 Code Quality

The project includes comprehensive code quality tools:

Checkstyle: Enforces Google Java Style Guide
PMD: Static analysis for potential issues
SpotBugs: Bug pattern detection
JaCoCo: Code coverage analysis (80% minimum coverage)

Run all quality checks:

./gradlew codeQuality

🔄 CI/CD Pipeline

The GitHub Actions workflow includes:

Multi-platform testing (Ubuntu, Windows, macOS)
Multi-Java version testing (Java 17, 21)
Code quality checks
Test coverage reporting
Dependency vulnerability scanning
Build artifact generation

📦 Dependencies

Key dependencies included:

Testing: JUnit 5, AssertJ, Mockito
Logging: SLF4J with Logback
Utilities: Apache Commons Lang, Google Guava
Kotlin: Standard library (for mixed projects)

🔧 Customization

Adding Dependencies

Add new dependencies in build.gradle.kts:

dependencies {
    implementation("group:artifact:version")
    testImplementation("test-group:test-artifact:version")
}

Modifying Package Structure

Update package names in build.gradle.kts
Move source files to new package structure
Update imports and references

Configuring Code Quality

Checkstyle: Edit config/checkstyle/checkstyle.xml
PMD: Edit config/pmd/ruleset.xml
SpotBugs: Edit config/spotbugs/exclude.xml

📋 Template Usage Guide

Files to Keep (Template Infrastructure)

Keep these files unchanged - they provide the template's core functionality:

📁 Configuration & Build
├── build.gradle.kts                 ✅ Keep (modify project details only)
├── settings.gradle.kts              ✅ Keep (update project name)
├── gradle.properties                ✅ Keep (corporate network settings)
├── gradlew / gradlew.bat            ✅ Keep (Gradle wrapper)
├── gradlew-corporate.*              ✅ Keep (corporate network scripts)
└── gradle/wrapper/                  ✅ Keep (Gradle wrapper files)

📁 Code Quality & CI/CD
├── .github/workflows/ci.yml         ✅ Keep (CI/CD pipeline)
├── .github/copilot-instructions.md  ✅ Keep (GitHub Copilot config)
├── config/checkstyle/               ✅ Keep (code quality rules)
├── config/pmd/                      ✅ Keep (static analysis)
├── config/spotbugs/                 ✅ Keep (bug detection)
└── .gitignore                       ✅ Keep (Git ignore rules)

📁 Documentation
├── CORPORATE-NETWORK-GUIDE.md       ✅ Keep (troubleshooting guide)
├── SETUP.md                         ✅ Keep (setup instructions)
├── setup-corporate-network.*        ✅ Keep (network setup scripts)
└── LICENSE                          ✅ Keep (or update for your license)

Files to Customize (Your Project Content)

Modify these files to match your specific project:

📁 Source Code - CUSTOMIZE
├── src/main/java/com/example/gradle/
│   └── App.java                     🔄 Replace with your main class
├── src/test/java/com/example/gradle/
│   └── AppTest.java                 🔄 Replace with your tests
└── src/main/resources/
    └── logback.xml                  🔄 Keep (modify logging config if needed)

📁 Documentation - CUSTOMIZE
├── README.md                        🔄 Update for your project
└── .github/template-repository.json 🔄 Update template metadata

Files to Remove (Template-Specific)

Delete these files after creating your project from the template:

📁 Template Cleanup - REMOVE
└── .github/template-cleanup/
    └── README.md                    ❌ Remove (template instructions only)

Template Checklist

When using this template:

Step 1: Project Configuration

Update project name in settings.gradle.kts
Modify build.gradle.kts application details:
- Change application.mainClass from "com.example.gradle.App"
- Update group name from "com.example"
Update repository name and description in this README

Step 2: Source Code

Replace src/main/java/com/example/gradle/ with your package structure
Create your main application class (replace App.java)
Replace example tests with your actual tests
Update package imports throughout the codebase

Step 3: Documentation

Customize this README for your project
Update SETUP.md if you have specific setup requirements
Modify .github/template-repository.json if creating another template
Update author information and license if needed

Step 4: Template Cleanup

Delete .github/template-cleanup/ directory
Remove template-specific sections from README
Commit your customized project

Step 5: Corporate Network (if applicable)

Test corporate network setup scripts work in your environment
Verify gradle.properties settings match your network requirements
Update CORPORATE-NETWORK-GUIDE.md with environment-specific details

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests and quality checks
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Gradle Boilerplate Project

🚀 Features

📁 Project Structure

🛠️ Prerequisites

� Corporate Network Setup

Quick Fix for Corporate Networks

Configuration Files

🚦 Quick Start

For Standard Networks

For Corporate Networks

📝 Available Gradle Tasks

Build Tasks

Testing Tasks

Code Quality Tasks

🧪 Testing

🔍 Code Quality

🔄 CI/CD Pipeline

📦 Dependencies

🔧 Customization

Adding Dependencies

Modifying Package Structure

Configuring Code Quality

📋 Template Usage Guide

Files to Keep (Template Infrastructure)

Files to Customize (Your Project Content)

Files to Remove (Template-Specific)

Template Checklist

Step 1: Project Configuration

Step 2: Source Code

Step 3: Documentation

Step 4: Template Cleanup

Step 5: Corporate Network (if applicable)

🤝 Contributing

📄 License

🔗 Related Resources

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Gradle Boilerplate Project

🚀 Features

📁 Project Structure

🛠️ Prerequisites

� Corporate Network Setup

Quick Fix for Corporate Networks

Configuration Files

🚦 Quick Start

For Standard Networks

For Corporate Networks

📝 Available Gradle Tasks

Build Tasks

Testing Tasks

Code Quality Tasks

🧪 Testing

🔍 Code Quality

🔄 CI/CD Pipeline

📦 Dependencies

🔧 Customization

Adding Dependencies

Modifying Package Structure

Configuring Code Quality

📋 Template Usage Guide

Files to Keep (Template Infrastructure)

Files to Customize (Your Project Content)

Files to Remove (Template-Specific)

Template Checklist

Step 1: Project Configuration

Step 2: Source Code

Step 3: Documentation

Step 4: Template Cleanup

Step 5: Corporate Network (if applicable)

🤝 Contributing

📄 License

🔗 Related Resources