spotube/.agents/skills/gradle/references/best_practices.md

Gradle Build Logic Best Practices

IMPORTANT: This document provides a high-level snapshot of common best practices. However, Gradle is a rapidly evolving tool. You MUST use the gradle_docs tool to retrieve the most up-to-date and comprehensive best practices directly from the official documentation.

1. Authoritative Research Workflow

Before implementing significant build logic, always perform a search for the latest recommendations using scoped queries and project context.

Example: Getting an Index of Best Practices

To find the authoritative index of best practices within the User Guide, first explore the userguide/ directory to identify the correct files.

Tool: gradle_docs

{
  "path": "userguide/",
  "projectRoot": "/absolute/path/to/project"
}

Reasoning: This call lists the contents of the userguide directory. Look for files starting with best_practices (e.g., best_practices.md, best_practices_dependency_management.md). Once identified, read the main index:

Tool: gradle_docs

{
  "path": "userguide/best_practices.md",
  "projectRoot": "/absolute/path/to/project"
}

Example: Searching for Best Practices

Tool: gradle_docs

{
  "query": "tag:best-practices dependency management",
  "projectRoot": "/absolute/path/to/project"
}

Reasoning: Using the authoritative best-practices tag ensures the returned content is filtered for high-signal architectural recommendations.

Example: Searching for Specific Guidance

Tool: gradle_docs

{
  "query": "tag:userguide performance best practices",
  "projectRoot": "/absolute/path/to/project"
}

---

2. Engine-Level Discovery (The "Source of Truth")

To understand the core architectural principles behind best practices, you can explore Gradle's own source documentation.

Example: Listing Core Concepts and Documentation

Use gradle_docs with path="." to explore the root documentation tree.

Tool: gradle_docs

{
  "path": ".",
  "projectRoot": "/absolute/path/to/project"
}

---

3. High-Level Snapshot (Current Guidelines)

The following sections summarize established idiomatic patterns. Use these as a starting point, but verify against the official docs.

Kotlin DSL Idiomatic Patterns

• Use Type-Safe Accessors: Prefer tasks.test { ... } or tasks.named<Test>("test") { ... } over tasks.getByName("test").
• Prefer register over create (Lazy APIs): Use tasks.register<MyTask>("myTask") to avoid eager task configuration.
• Use Lazy Properties: Employ the Property<T> and Provider<T> APIs for late binding and better configuration cache compatibility.

Performance & Configuration Cache

• Enable Configuration Cache: Ensure build logic avoids accessing the Project object inside task actions.
• Use Specific Annotations: Properly label task properties with @Input, @OutputFiles, @Internal, etc.
• Minimize Logic in Build Scripts: Move complex logic into convention plugins or buildSrc.

Dependency Management

• Use Version Catalogs: Centralize dependencies in gradle/libs.versions.toml.
• Avoid allprojects and subprojects: These blocks create tight coupling; use convention plugins and apply them selectively instead.

Project Integrity

• Reproducible Builds: Use fixed versions and commit the Gradle wrapper.
• Surgical Updates: Only update what is necessary and verify with check.

Resources (Official Source of Truth)

• Official Gradle Best Practices
• Gradle Performance Guide
• Kotlin DSL Primer