[MDEPLOY-265] Maintain backwards compatibility for alt*DeploymentRepository in id::default::url format

[philsttr]

[MDEPLOY-265] Maintain backwards compatibility for alt*DeploymentRepository in id::default::url format

The legacy format (<=2.x) of alt*DeploymentRepository is id::layout::url.
The new format (>= 3.x) of alt*DeploymentRepository is id::url, which is equivalent to id::default::url from the legacy format.

This change introduces backwards compatibility with 2.x by supporting alt*DeploymentRepository values in the id::layout::url format if and only if the layout is equal to default. The default layout is the most commonly used layout, so this should maintain backwards compatibility with the large majority of projects using the alt*DeploymentRepository properties.

Usage of the legacy format with the default layout will result in a warning message being logged.
Usage of the legacy format with layouts other than default will result in an exception being thrown.

One use case this change will help is when alt*DeploymentRepository properties are set in common maven settings.xml files used for a large number of projects. For example, a CI server. Keeping backwards compatibility with id::default::url allows those settings.xml files to be used regardless of the version of maven-deploy-plugin used by the projects built on that CI server. Projects can individually upgrade their maven-deploy-plugin without breaking.

Following this checklist to help us incorporate your
contribution quickly and easily:

• Make sure there is a JIRA issue filed
  for the change (usually before you start working on it). Trivial changes like typos do not
  require a JIRA issue. Your pull request should address just this issue, without
  pulling in other changes.
• Each commit in the pull request should have a meaningful subject line and body.
• Format the pull request title like [MPH-XXX] - Fixes bug in ApproximateQuantiles,
  where you replace MPH-XXX with the appropriate JIRA issue. Best practice
  is to use the JIRA issue title in the pull request title and in the first line of the
  commit message.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Run mvn clean verify to make sure basic checks pass. A more thorough check will
  be performed on your pull request automatically.
• You have run the integration tests successfully (mvn -Prun-its clean verify).

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

• In any other case, please file an Apache Individual Contributor License Agreement.

[michael-o]

@cstamas WDYT?

[cstamas]

My original change was doing exactly this, so I am +1 on this (so "legacy syntax w/ default layout should work + warn), but there was a discussion where we agreed that ANY unexpected syntax should fail the build.
#12 (comment)

So, again, I am +1, but @mickroll?

[mickroll]

So, again, I am +1, but @mickroll?

Build Warning is fine aswell. 👍

[michael-o]

Hmm, this should have happened pre 3.0.0 🤣. My proposal is to allow this during milestone phase, but ultimately drop with GA.

[philsttr]

FWIW, I would like to keep these changes in 3.0 GA. For me, it's not useful unless it makes it into GA. It seems like such a small amount of code for huge wins in compatibility.

[michael-o]

Let me think about that and come back to you later.

[michael-o]

Can you please describe why this is so important to you since this is a non-standard case?

[philsttr]

Sure thing.

We have an artifactory instance in our corporate environment to which we deploy thousands of our own artifacts. This is a large corporate environment that supports many, many dev teams.

We do not specify a distributionManagement section in our thousands of git repositories. Instead, we specify the alt*DeploymentRepository properties in a maven settings.xml file (simplified example) on our CI servers. When the thousands of git repositories are built using these CI servers, they automatically pick up the alt*DeploymentRepository values from the maven settings.xml files. This gives us a central place to manage where artifacts are deployed. This approach has proven invaluable at times, since we've gone through a few artifactory migrations, and have had to redirect things several times over the last few years.

We want to allow projects to upgrade the version of maven-deploy-plugin used in their projects at their own pace. And we want the builds to continue to work and deploy correctly when they do upgrade maven-deploy-plugin without any other changes to the build pipeline. This transparency requires backwards compatibility of the alt*DeploymentRepository value format, since they all use the same settings.xml file.

There are several alternatives, but none are very desirable

1. Stop using alt*DeploymentRepository, and use distributionManagement in each repo, or in parent poms. This requires each repo to be updated any time we need to change the distribution settings. This is not scalable.
2. Create separate settings.xml files for each alt*DeploymentRepository value format. This does not allow repos to transparently upgrade maven-deploy-plugin. The builds will break when maven-deploy-plugin is upgraded. The build pipeline for each individual repo would then need to be modified to use different settings.xml file. This is not something I want to expose to the vast majority of other developers, since they do not need to be aware of the distribution management settings to get their job done.

In short, not maintaining backwards compatibility of this format will cause us a tremendous amount of toil. That toil can be easily avoided if the format remains backwards compatible. The code to keep backwards compatibility is straightforward and simple, and totally worth it.

[cstamas]

I agree with Phil. 3.0.0-M1 made it wrong: old param syntax should be deprecated but usable (like this PR makes it), not unsupported. 4.x may drop legacy (deprecated) syntax completely, IMO

[michael-o]

@philsttr Thanks for your elaboration. There are few nits with your settings which you should correct:

• When defining central in a profile point to a non-existent URL so your mirror will do the right thing
• Do not use central for deployment repos. You never logically deploy to it, use your own id please

Now back to your approach: As far as I understand the target repo does not depend on the group/artifact id, but no the CI server performing actions?

[philsttr]

the target repo does not depend on the group/artifact id, but no the CI server performing actions?

(I do not quite understand the question, but I'll attempt to answer what I think you are asking. If this does not answer your question, please clarify the question.)

Each of our many repos define their dependencies and plugins, and version of each. They are free to use whatever they need. They are currently using various versions of the maven-deploy-plugin (but not 3.0.0-M1, since that broke compatibility).

The CI server does not define dependencies, plugins, or versions.

[michael-o]

Sorry for the confusion. There was a nasty typo in my question. I wll rephrase: How do you know/decide on the CI server to which hosted repo a deployment will go and why is not possible to have that kind of information staticially in the POMs?

[philsttr]

We have one shared artifactory instance to which all artifacts are published. All CI servers use the same settings.xml file, which causes artifacts to publish to the same repositories on the shared artifactory instance. The example settings.xml file shows that artifacts are published to one of three repositories on the shared artifactory instance (either maven-releases, maven-snapshots, or maven-combined)

We prefer to centrally manage the distribution settings on our CI servers via settings.xml files rather than poms. We do this mainly because we have few CI servers (less than 5), and many poms (thousands). If/when we need to change these settings, it's a trivial task to update the CI servers. By comparison, to update all the poms would be a monumental task of distributed effort across many dev teams and release cycles. It's just not a scalable solution. Note that this isn't just a theoretical exercise. We have had to update these settings several times over the past few years due to changes to our artifactory infrastructure.

[michael-o]

OK, let me summarize: You update at most 5 CI servers for new URLs instead to manipulate the corporate POM and then need to update all dependend projects (thousands)?

[philsttr]

Correct.

And to clarify 'you' in your statement... the infrastructure teams handle the updates to CI, settings.xml, and artifactory. It's transparent to developers. Devs don't need to know anything about this stuff. All they need to know is to create a maven project, and the artifacts are deployed where they are supposed to go automatically.

[michael-o]

But you still have to maintain developer settings to resolve artifactsduring coding, right?

[philsttr]

Yes, the same settings.xml file is used by developers as part of automated dev environment setup/maintenance.
Technically only the mirror portion is needed by devs, since devs don’t have access to deploy to artifactory. Only CI can deploy.

[michael-o]

Thank you very much making your setup clear. I will re-review this PR today and go ahead with the merge.

[michael-o]

@philsttr It'd be awesome if you could share/write down your approach as a single page for our Maven Site Guides as "Large Scale Centralized Deployments with Maven".

[philsttr]

@michael-o I'd be happy to. Where are the Maven Site Guides located? Can you point me to where I should submit a PR?

[michael-o]

https://github.com/apache/maven-site/tree/master/content/apt/guides