Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add note about sbtPluginPublishLegacyMavenStyle #1164

Merged
merged 3 commits into from
Feb 17, 2024
Merged

Add note about sbtPluginPublishLegacyMavenStyle #1164

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d696bc9
Add note about sbtPluginPublishLegacyMavenStyle
ghostbuster91 Nov 1, 2023
88d6638
Update src/reference/02-DetailTopics/05-Plugins-and-Best-Practices/02…
ghostbuster91 Jan 7, 2024
5e30d3c
Unify naming and drop not-important details
ghostbuster91 Jan 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions src/reference/02-DetailTopics/05-Plugins-and-Best-Practices/02-Plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -508,6 +508,29 @@ libraryDependencies ++=
Seq.empty
```

### Publishing a plugin

Sbt plugins can be published as any other projects.

However, there is one caveat if you attempt to publish your plugin to a repository that follows the Maven scheme.
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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


If your artifacts repository expect artifacts to be compliant with maven scheme and rejects artifacts that does no adhere to it you can:
1. If you and consumers of your plugin use sbt 1.9.x

Since sbt 1.9, it tries to publish any plugin with the new and legacy Maven style (for backward compatibility). The legacy Maven style is not fully compatible with Maven scheme.
You need to disable it with:
`sbtPluginPublishLegacyMavenStyle := false`
Notice that you won't be able to consume this plugin with sbt older than 1.9, as it can only resolve the legacy Maven style (or you need to use the trick described in [sbt-vspp](https://github.com/esbeetee/sbt-vspp)).
3. If you use sbt < 1.9.x

You can use https://github.com/esbeetee/sbt-vspp/
5. If you cannot use sbt 1.9.x and you cannot/don't want to use sbt-vspp
Comment on lines +523 to +527
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@ghostbuster91 ghostbuster91 Jan 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


There should be an option like `Suppress POM Consistency Checks` in your artifactory settings that will allow you to submit artifacts even if they don't fully follow maven scheme.

You can find more details about this in the [following issue](https://github.com/sbt/sbt/issues/3410).

### Best Practices

If you're a plugin writer, please consult the [Plugins Best Practices][Plugins-Best-Practices]
Expand Down