Skip to content

Commit 9c15610

Browse files
committed
Fail the API check when its options narrow it outside an X.0.0 version
An empty comparison, <includes>, <overrideCompatibilityChangeParameters>, a public-only <accessModifier> or <includeSynthetic>false hid a break the same way <excludes> did. The message now covers excludes left over from a major that just shipped.
1 parent 02d55f4 commit 9c15610

3 files changed

Lines changed: 32 additions & 10 deletions

File tree

‎AGENTS.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ Bugfixes and small features stop at this skill.
4747
## Releases
4848

4949
Follow the [Releasing a version](https://github.com/graphql-java-kickstart/graphql-java-tools/wiki/Releasing-a-version) wiki
50-
page. `github-build.sh` and `.github/workflows/release.yml` do the version bump, tag and publish.
50+
page. `github-build.sh` and `.github/workflows/release.yml` do the version bump, tag and publish. After an X.0.0 release,
51+
delete the `<excludes>` under japicmp-maven-plugin in `pom.xml`. The version is X.0.1-SNAPSHOT by then and the API check
52+
fails while they remain.
5153

5254
## Rules that need judgment
5355

@@ -86,7 +88,7 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
8688
| Argument conversion goes through one entry point | docs only |
8789
| An input field's Java type comes from the mapping Jackson uses, not from guessed getters | docs only |
8890
| Every recursive walk over the type graph handles cycles, and a test covers a cycle | docs only |
89-
| Public signatures stay binary compatible, data class `copy()` and `componentN` included | japicmp with `build/japicmp-kotlin-public.groovy` at `mvn verify`, excludes only at an X.0.0 version |
91+
| Public signatures stay binary compatible, data class `copy()` and `componentN` included | japicmp with `build/japicmp-kotlin-public.groovy` at `mvn verify`, which allows excludes and other narrowing options only at an X.0.0 version |
9092
| Remove the plumbing a change leaves unused | Compiler warnings for unused locals, docs only for the rest |
9193
| A new warning or build error names the type and the item and uses `SourceLocation.describe()` for its location | docs only |
9294
| A check keyed on a class name or an exception type has a test that fails when the dependency moves it | docs only |

‎build/japicmp-kotlin-public.groovy‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import javassist.bytecode.InnerClassesAttribute
66
import javassist.bytecode.annotation.ArrayMemberValue
77
import javassist.bytecode.annotation.IntegerMemberValue
88
import javassist.bytecode.annotation.StringMemberValue
9+
import japicmp.model.AccessModifier
910
import kotlin.metadata.Attributes
1011
import kotlin.metadata.Visibility
1112
import kotlin.metadata.jvm.JvmExtensionsKt
@@ -105,20 +106,39 @@ def classSide = { CtClass ctClass ->
105106
side
106107
}
107108

108-
// japicmp hands this script only the classes, so the excludes come from its options and the version from the pom.properties
109+
// japicmp passes every class of both jars, filtered only by its options, so no classes means the options filter out the
110+
// whole jar.
111+
if (jApiClasses.isEmpty()) {
112+
throw new IllegalStateException("japicmp-maven-plugin compared no classes, so its <includes> or <excludes> leave out the " +
113+
"whole jar and no break can fail the build. Remove them. A break planned for the next major gets an <exclude> naming " +
114+
"that member, with the version set to that major's X.0.0-SNAPSHOT.")
115+
}
116+
117+
// japicmp hands this script only the classes, so the options come from a class and the version from the pom.properties
109118
// maven-jar-plugin puts in the jar under comparison.
110-
def excludes = jApiClasses.isEmpty() ? [] : jApiClasses.first().@options.filters.excludes*.toString().unique()
111-
if (!excludes.isEmpty()) {
119+
def options = jApiClasses.first().@options
120+
def narrowing = [
121+
'<excludes>' : options.filters.excludes*.toString().unique(),
122+
'<includes>' : options.filters.includes*.toString().unique(),
123+
'<overrideCompatibilityChangeParameters>': options.overrideCompatibilityChanges.collect {
124+
"${it.compatibilityChange} binaryCompatible=${it.binaryCompatible}"
125+
},
126+
'<accessModifier>' : options.accessModifier == AccessModifier.PROTECTED ? [] : [options.accessModifier.name()],
127+
'<includeSynthetic>' : options.includeSynthetic ? [] : ['false'],
128+
].findAll { name, values -> !values.isEmpty() }
129+
if (!narrowing.isEmpty()) {
112130
def newClass = jApiClasses.find { it.newClass.present }.newClass.get()
113131
def jar = ((JarURLConnection) newClass.classPool.find(newClass.name).openConnection()).jarFile
114132
def pomProperties = new Properties()
115133
pomProperties.load(jar.getInputStream(jar.entries().find { it.name.startsWith('META-INF/maven/') && it.name.endsWith('/pom.properties') }))
116134
def version = pomProperties.getProperty('version')
117135
if (!(version ==~ /\d+\.0\.0(-SNAPSHOT)?/)) {
118-
throw new IllegalStateException("japicmp-maven-plugin has <excludes> at version ${version}, which compares against a " +
119-
"release of the same major:\n" + excludes.collect { " ${it}" }.join('\n') + "\nExcludes are only for breaks planned for the next major, " +
120-
"with the version set to that major's X.0.0-SNAPSHOT. Remove them and keep the old signature as a @Deprecated overload " +
121-
"instead. In Kotlin, @Deprecated(level = DeprecationLevel.HIDDEN) keeps it for compiled callers only.")
136+
def major = version.substring(0, version.indexOf('.'))
137+
throw new IllegalStateException("japicmp-maven-plugin narrows the API check at version ${version}, which is not an X.0.0 " +
138+
"version:\n" + narrowing.collect { name, values -> " ${name}: ${values.join(', ')}" }.join('\n') +
139+
"\nOnly a major's X.0.0-SNAPSHOT may narrow it, for the breaks that major plans. If these belong to the ${major}.0.0 " +
140+
"release that just shipped, delete them. Otherwise delete them and keep the old signature as a @Deprecated overload. " +
141+
"In Kotlin, @Deprecated(level = DeprecationLevel.HIDDEN) keeps it for compiled callers only.")
122142
}
123143
}
124144

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -284,7 +284,7 @@
284284
</execution>
285285
</executions>
286286
</plugin>
287-
<!-- Ant's <fail> puts the jar check's reason in Maven's last error line, where exec-maven-plugin prints a stack trace -->
287+
<!-- Ant's <fail> makes the jar check's reason Maven's last error line, with no stack trace -->
288288
<plugin>
289289
<groupId>org.apache.maven.plugins</groupId>
290290
<artifactId>maven-antrun-plugin</artifactId>

0 commit comments

Comments
 (0)