Change to scope of API Guardian dependency breaks builds with custom Gradle `Configuration`

[sbrannen]

Overview

The change in c5ee49d breaks existing Gradle builds.

For example, the Spring Framework is using Gradle 6.8.3, and when the build is upgraded to JUnit 5.8 snapshots the build fails with numerous errors similar to the following.

> Task :spring-test:compileJava FAILED
/Users/sbrannen/.gradle/caches/modules-2/files-2.1/org.junit.jupiter/junit-jupiter-api/5.8.0-SNAPSHOT/617bb4ea90ad07de26681dd57932575b534ec15e/junit-jupiter-api-5.8.0-SNAPSHOT.jar(org/junit/jupiter/api/extension/ExtendWith.class): warning: Cannot find annotation method 'status()' in type 'API': class file for org.apiguardian.api.API not found
warning: unknown enum constant Status.STABLE
  reason: class file for org.apiguardian.api.API$Status not found

Workaround

Adding compileOnly("org.apiguardian:apiguardian-api") to spring-test allows the spring-test module to build.

Deliverables

• Document as a potentially breaking change in the release notes.

[sbrannen]

The Maven POM for junit-jupiter-api for the latest snapshot contains the following.

<dependency>
    <groupId>org.apiguardian</groupId>
    <artifactId>apiguardian-api</artifactId>
    <version>1.1.2</version>
    <scope>compile</scope>
</dependency>

So it looks like the change doesn't affect Maven builds.

[sbrannen]

By comparing the Gradle module files from 5.8 M1 and 5.8 GA snapshots -- for example junit-jupiter-api-5.8.0-M1.module vs junit-jupiter-api-5.8.0-20210902.134413-315.module -- we see that the apiguardian-api dependency moved from runtimeElements to apiElements.

Note that the spring-test module declares its dependencies on JUnit Jupiter as follows.

optional("org.junit.jupiter:junit-jupiter-api")

From the documentation of Spring Framework's OptionalDependenciesPlugin:

The optional configuration is part of the project's compile and runtime classpaths but does not affect the classpath of dependent projects.

/cc @bclozel, @wilkinsona

[wilkinsona]

We might need to configure some attributes on the optional configuration so that it consumes from apiElements.

[sbrannen]

FYI: Spring Framework's optional configuration has been updated to properly work with apiElements in spring-projects/spring-framework#27365.

In light of that, we may consider this a necessary enhancement to Spring's build instead of a bug in JUnit.

However, other projects out there might run into similar issues with custom dependency configuration. So I'll leave this issue open for team discussion before releasing 5.8 GA.