[MNG-8485] Finalize Maven 4 API

[jira-importer]

Elliotte Rusty Harold opened MNG-8485 and commented

Roughly 200 classes and interfaces in Maven core are annotated @Experimental . There might be a reason to ship a few things in 4.0 that might still change but 200 is far too many. Commit to these APIs (i.e. remove the annotation) or fix and/or remove those types.

Ar least some of them such as org.apache.maven.api.services.BaseRequest are already package protected, in which case we don't need the annotation at all.

Things to fix:

There are two ProblemCollector interfaces. Rename one or combine them.

---

Affects: 4.0.0-rc-2

Issue Links:

• MNG-8488 Finish javadoc for Maven 4 API

Remote Links:

• GitHub Pull Request #2036
  
• GitHub Pull Request #2039
  

[jira-importer]

Guillaume Nodet commented

It's hard to commit to the API if it's not battle tested.
How many plugins have been migrated to the new API ?
Not even all core plugins have been migrated...

[jira-importer]

Elliotte Rusty Harold commented

It is a chicken and egg problem. That said, if we're not committing to the API we're not for an RC, much less a final release. We soould update enough plugins that we're confident in the API

[jira-importer]

Guillaume Nodet commented

Not sure why this is a chicken and egg. Maven 4 is totally usable with Maven 3 plugins. It contains a bunch of enhancements which would be nice to deliver, even if the Maven 4 API is finalised in 4.1.0 or 4.2.0 release. Why is that a problem ?

[jira-importer]

Elliotte Rusty Harold commented

Checken and egg: we can't ship before committing to the API and we can't commit to the API before shipping. I think it's actually the second point that needs to bend. We need to review the APIs and remove the experimental tag. Let's not ask anyone to code to an unstable API.

[jira-importer]

Guillaume Nodet commented

Why "we can't ship before committing to the API" ?
We do not force anyone using Maven 4 to migrate their plugins to the new API.
I don't see any good reason that would not let us ship the API in preview for 4.0.

[jira-importer]

Elliotte Rusty Harold commented

IMHO when the API isn't frozen you're at alpha stage, not even beta, much less release candidate or release. Once we release a finished version, API stability is critical. Violate that and we'll lose a big chunk of the developer base. (This is also a good reason to keep APIs small and non-public to the extent possible, so there's less to commit to.)

[jira-importer]

Sylwester Lachiewicz commented

I saw many projects from "us" got stuck with old Maven 4.x like beta-5 or even before beta5.
For some we have open, not finished PR, for others, Dependabot has opened PR but due to API changes - all require manual migration.
Not sure what people would feel when They need to move their plugins to API 4.x without any automatic way to migrate - like the OpenRewrite recipe.
Doxia 2.x migration was also painful to us, mainly to tech debt.

[jira-importer]

Elliotte Rusty Harold commented

Yes, this. I don't think we can avoid the pain of migration (unless we're willing to cancel 4.x) but at least let's make it a one time rip-the-bandaid-off event, not something that happens repeatedly every few months as new releases trickle out with subtle and not-so-subtle changes to the API.

[jira-importer]

Guillaume Nodet commented

I think we can split two things:

• release Maven 4
• freeze the new API

There's absolutely no technical reason this cannot be done.

No plugins have been officially released in GA anyway, so we can definitely continue releasing them as beta until the API is frozen. When a sufficient number of plugins have been migrated, we freeze the API and announce it. Whether it is in 4.1, 4.2 or 4.5 is irrelevant.

The JDK also does that with preview APIs that are rewritten between releases. I don't see that as a problem. Quite the opposite, it allows battle testing APIs in a shorter time frame. That's exactly what we need.

Why couldn't we do the same ?

[jira-importer]

Elliotte Rusty Harold commented

There's of course no technical reason. This is about the developer experience.

Preview APIs are a thing, but I also don't think it's OK to release most major APIs for core functionality as preview.

I'm not sure what you mean by "No plugins have been officially released in GA". We don't seem to use the term GA in the Maven project, but dozens of plugins have been released and stable post-1.0 for years. I'd call that GA.

[jira-importer]

Guillaume Nodet commented

There's of course no technical reason. This is about the developer experience.

It seems to me that this is a communication / documentation problem.
And if we look at https://github.com/apache/maven-site/blob/99ea2cca3ee1fbce6b4b16f7ee53966473a441a3/content/markdown/whatsnewinmaven4.md (which I haven't written), the new API is not even mentioned.
Of course, given we deprecated a lot of Maven 3 APIs, if developers start writing plugins and use Maven 4 dependencies, they will probably see all those warnings that redirect them to the new API. We'll have to communicate clearly the state of the API, the fact that we're still in preview and need feedback.

Preview APIs are a thing, but I also don't think it's OK to release most major APIs for core functionality as preview.

Not sure to follow. I would think the exact opposite. Since it's such a big thing, we definitely want to make sure it's mature and stable before making it official. We could delay Maven 4 another few years, but it still contains new features that are useful to users, so I'd rather have a way to delivery those and have a more iterative release schedule, rather than delaying for years.

I'm not sure what you mean by "No plugins have been officially released in GA". We don't seem to use the term GA in the Maven project, but dozens of plugins have been released and stable post-1.0 for years. I'd call that GA.

Sorry, I was unclear. I meant that we have not released any stable plugin using the new Maven API. We did release a few in beta only.

[jira-importer]

Elliotte Rusty Harold commented

Former employees of a certain large tech company will recognize the antipattern here. There are two APIs: the deprecated one and the one that doesn't work yet. We shouldn't be deprecating things until the replacement is ready.

[jira-importer]

Guillaume Nodet commented

There are two APIs: the deprecated one and the one that doesn't work yet. We shouldn't be deprecating things until the replacement is ready.

Yes, that's right. I'm not sure this is a big problem as it's not really as if you could use one or the other and mix/match. Those are two separate worlds: Maven 3 plugins and Maven 4 plugins. Plugin developers will need to choose a target and I think developers that want to write a Maven 3 plugins should use the Maven 3 artifacts (where the Maven 3 API is not deprecated).
It's not as if we were deprecating one class or method in favour of another: the whole API which is scattered in multiple artifacts / packages / and even projects is deprecated.

Deprecation is technical way to communicate informations to users. And we need to communicate clearly our intent. I'm fine with undeprecating the Maven 3 API in Maven 4, and make it deprecated when we release the new API. But in all cases, we need to communicate to users that it will be deprecated in the coming months. And imho, that kinda means it's already deprecated, but with no replacement yet.

[jira-importer]

Elliotte Rusty Harold commented

Things to fix:

There are two ProblemCollector interfaces. Rename one or combine them.

[jira-importer]

Guillaume Nodet commented

One of those is deprecated with #2043 as not part of the Maven 4 API.