Add note about sbtPluginPublishLegacyMavenStyle

[ghostbuster91]

Relates to sbt/sbt#3410

[kubukoz]

Suggested change

	For many years, Sbt plugins have utilized an artifact layout that is incompatible with Maven-based repositories, and rectifying this in a fully compatible manner has proven to be quite challenging.
	For many years, sbt plugins have utilized an artifact layout that is incompatible with Maven-based repositories, and rectifying this in a fully compatible manner has proven to be quite challenging.

[eed3si9n]

I feel like this sentence is simultaneously too much detail for someone who might be interested in creating a new plugin, and not enough details to accurate capture the problem with pre-1.9 publishing. I don't know if it's clear what was "incompatible" with what, for instance. Maven Central has allowed sbt to publish, and sbt versions going back for many years sbt using either Ivy or Coursier was able to resolve plugins out of Maven Central, so it was compatible in that sense.

The problem with pre-1.9 sbt was that it published in a compatible, but intentionally invalid URL such as https://repo1.maven.org/maven2/com/eed3si9n/sbt-assembly_2.12_1.0/2.1.4/sbt-assembly-2.1.4.pom because the artifactId of the module is called sbt-assembly:

<artifactId>sbt-assembly</artifactId>

This was a workaround to preserve the name from sbt as artifactId, while allowing Apache Ivy to find the _2.12_1.0 variant of sbt-assembly from a Maven repository. In an Ivy-layout repository, this concept is expressed as extra attributes, and therefore sbt team has initially recommended hosting sbt plugins on Ivy repository on Artifactory or Bintray. Preserving the name of module allows sbt to round-trip the POM back to our idea of modules, but also it has allowed external services such as https://search.maven.org/search?q=sbt-assembly to treat sbt-assembly as "sbt-assembly", not "sbt-assembly_2.12_1.0" etc.

This invalidity have been ok, apart from the fact that Artifactory has a checkbox called "Suppress POM Consistency Checks", and tried to enforce consistency of the URL layout. Post-1.9 sbt will double-publish to https://repo1.maven.org/maven2/com/eed3si9n/sbt-assembly_2.12_1.0/2.1.4/sbt-assembly_2.12_1.0-2.1.4.pom so the URL as well as the artifactId are now valid:

<artifactId>sbt-assembly_2.12_1.0</artifactId>

[ghostbuster91]

I decided to drop this sentence as it indeed wasn't bringing much value.

[eed3si9n]

The official doc should be written based on the narrative that you should just use the latest stable version of sbt, since if anyone opening a GitHub issue would be told to do so anyway.

[ghostbuster91]

I marked the first option as recommended, I agree that people should use the latest versions in general, but as we all know well it is simpler said than done. Sometimes there are things that temporarily prevent migration to more recent versions.

Is the current form ok?

[eed3si9n]

Thanks for the contribution. This would be a useful information to note.

[ghostbuster91]

Thanks for the contribution. This would be a useful information to note.

Thanks for the feedback, I think I addressed most of it and sorry for the long delay.

[ghostbuster91]

@eed3si9n @xuwei-k hi guys, just a friendly reminder about this one. It's been reviewed and approved, could we please have it merged at your earliest convenience? Thank you!

[eed3si9n]

Merged