# ADR-0006 - Use of Provider APIs in Gradle

## Status

- ACCEPTED on 2024-06-21

## Context

* **Consistency with dependencies**: Gradle's ecosystem and dependencies predominantly use American English

### Exceptions

Some legitimate exceptions exist where British English or other variants must be preserved:

* **Third-party APIs and libraries**: When integrating with external APIs that use different spelling conventions

Historically, Gradle has shipped with some Groovy types in very prominent APIs.
This required the Kotlin DSL to add special integration to work with Groovy closures.
This has also forced plugins written in languages other than Groovy to use Groovy types for some APIs.

When the Kotlin DSL was introduced, we made an effort to add non-Groovy equivalents for all APIs.

      When doing so, still annotate nullable parameters and the return type as `@Nullable`.
  * Do not use `@Contract` for public APIs.
  * For polynull public APIs, the solution has to be decided on a case-by-case basis.

Do not remove `null` checks on public API boundaries, even if the annotations (or rather lack of them) suggest this.

            // Filter out any non-public APIs
            f.exclude(PublicApi.INSTANCE.getExcludes());
        }));
        extension.getKotlinDslSource().from(sourcesPath.getIncoming().artifactView(v -> v.lenient(true)).getFiles().getAsFileTree().matching(f -> {
            f.include(PublicKotlinDslApi.INSTANCE.getIncludes());
            // Filter out any non-public APIs

- User prompting services.
- Build options infrastructure.
- The console and CLI, as a specific implementation of these services.

The UI architecture module uses the core runtime architecture module. It provides APIs that are used by the other modules and platforms. 

This ADR does not specify the owner of this new architecture module. However, as a separate module, it can be assigned ownership independently of the other core services.

platforms/documentation/docs/src/docs/userguide/reference/dsl-apis/kotlin_dsl.adoc                          @gradle/bt-docs-reviewers @gradle/bt-tide
platforms/documentation/docs/src/docs/userguide/reference/dsl-apis/migrating_from_groovy_to_kotlin_dsl.adoc @gradle/bt-docs-reviewers @gradle/bt-tide

## Decision

Organize the Gradle code base into a set of coarse-grained "architecture modules".
An architecture module is responsible for providing a coherent set of features and:

- Provides a set of APIs and services for use from outside the module.
- Has a private implementation.
- Is owned by a single team. A team may own multiple architecture modules.

The modules are arranged into several different "Gradle platforms".

                    "API Compatibility Report",
                    "$HIDDEN_ARTIFACT_DESTINATION/report-architecture-test-binary-compatibility-report.html",
                )
                buildReportTab("Incubating APIs Report", "incubation-reports/all-incubating.html")
            }
            if (stage.performanceTests.isNotEmpty()) {
                buildReportTab("Performance", "performance-test-results.zip!report/index.html")
            }

- `@Execute` marks web endpoints
- `@Resource` for DI
- `@Secured({ "role", "role-view" })` for authorization
- Return `HtmlResponse` for JSP, `JsonResponse` for APIs

### Service
- Inject behaviors (Bhv) for data access
- Use `OptionalEntity<T>` for nullable returns
- Plain classes (no extends/implements)

### Helper
- Stateless utility classes