Eliminate trailing double newline in dump

[JakeWharton]

Closes #133

[JakeWharton]

The fact that you can add multiple dump files and have them magically joined is weird. It's only used in one test. That test should specify a combined file and this functionality should be eliminated.

Can do in a follow-up if you agree.

[fzhinkin]

It's not only about dumps, and I personally find it quite convenient when it comes to constructing Gradle build scripts, like here:

binary-compatibility-validator/src/functionalTest/kotlin/kotlinx/validation/test/InputJarTest.kt

Line 18 in 218728f

resolve("/examples/gradle/configuration/jarAsInput/inputJar.gradle.kts")

[JakeWharton]

Another testing oddity. This fundamentally undermines the ability to validate the textual representation of the dump and prevented actually asserting against the behavior change in this PR.

The presence or absence of trailing whitespace on a line and the presence or absence of trailing newlines are part of the output and should be validated as such.

[fzhinkin]

@JakeWharton thanks for addressing the issue. Sorry for the long time it's taking me to review it, I'll look at it this week.

[JakeWharton]

Sure, no rush. Thanks. I'll do a rebase in the mean time later today.

[fzhinkin]

I'm not 100% sure if a double newline at the end of a dump was intentional (@ilya-g correct me if it was), but changing it right now will annoy a lot of users as their dumps will no longer pass validation.

So, at least KotlinApiCompareTask has to be update to ignore trailing newlines.
I would also add a dump overload accepting a parameter controlling trailing newlines and preserve the current behavior for the old overload, so that existing dump users (like Kotlin stdlib) won't experience any changes in a dump format:

public fun <T : Appendable> List<ClassBinarySignature>.dump(to: T): T = dumpTo(to, true)
public fun <T : Appendable> List<ClassBinarySignature>.dump(to: T, addTrailingNewline: Boolean): T { .. }

[JakeWharton]

The format has changed before in minor version bumps. Since the next version is a minor version bump, perhaps we can instead warn if the double trailing newline is present. And then remove that for 0.16 where we only accept the new format.

[fzhinkin]

The format has changed before in minor version bumps.

That's true, but it was usually associated with improvements in public ABI handling, not just the format itself.

Since the next version is a minor version bump, perhaps we can instead warn if the double trailing newline is present. And then remove that for 0.16 where we only accept the new format.

The fix is about cleaning up the mess BCV made previously itself, not something users deliberately made themselves. So I don't think we should bother users if there's an option to slightly change KotlinApiCompareTask's behavior and make everything unnoticeable (for those who don't update the dump, ofc).