You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by GitBox <gi...@apache.org> on 2020/12/29 02:45:09 UTC
[GitHub] [maven-site] philsttr opened a new pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
philsttr opened a new pull request #223:
URL: https://github.com/apache/maven-site/pull/223
Suggested by @michael-o via https://github.com/apache/maven-deploy-plugin/pull/15#issuecomment-750933613
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550285056
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
I agree that relying on default versions is not the best practice, and I also actively encourage specifying explicit versions. Unfortunately, in a large scale environment, we cannot instantly change all projects to not do it. People will use it because it is easy, or they don't know better, or they aren't that familiar with maven, or they don't even know that the maven-deploy-plugin is being used (since they never use it directly, only CI uses it).
I still think how to handle old maven-deploy-plugin versions needs to be mentioned for the guide to be most helpful to the target audience. The people reading the guide will probably have to deal with older projects using older versions of the maven-deploy-plugin, and (like me) cannot instantly upgrade thousands of poms even if they wanted to.
And the inability to instantly upgrade thousands of poms is also the reason we don't use `<distributionManagement>` at all in the pom anymore, even with a custom property like @khmarbaise mentioned. The first time we rolled out this change, years ago, we needed to override the existing `<distributionManagement>` section in poms (that did not use a custom property), so we used the properties utilized by maven-deploy-plugin directly, and added properties supported by all versions of maven-deploy-plugin in use. Even if we started today, I'd still use the maven-deploy-plugin's properties, rather than custom properties just so there are no requirements in poms at all.
I favor centralizing all of the upload/download configuration in settings.xml files, without anything specific needed in the poms. In fact (side-note), I wish there was a `<distributionManagement>` section in the settings.xml file. Since downloads have first-class support in settings.xml files via the mirrors section, it makes logical sense that uploads should also have first-class support in settings.xml files. Perhaps that is a feature request for Maven 4.0.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550377021
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (Only needed if some projects are still using maven-deploy-plugin \< 2.8.
+ See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+ The following sections describe how to configure Maven clients to:
+
+ * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository.
+
+ * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the local repositories.
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by Maven projects in the organization should be downloaded
+ from the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the Maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's Maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by Maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the Maven <<<settings.xml>>> file.
+ When these properties are defined, the maven-deploy-plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}}
+ goal uses them instead of the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files
+ to determine where to upload artifacts.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files if/when the distribution locations need to change.
+
+ The ability to specify separate alternate deployment repositories for releases and snapshots
+ via the <<<altReleaseDeploymentRepository>>> and <<<altSnapshotDeploymentRepository>>> properties,
+ respectively, was added in maven-deploy-plugin 2.8.
+ To get the most out of the approach defined in this document, all projects should use maven-deploy-plugin \>=2.8.
+ If some projects are still using an older version of maven-deploy-plugin (\>=2.3 and \<2.8), then
+ specify a single alternate deployment repository via the <<<altDeploymentRepository>>> property
+ that points to a repository capable of containing both releases and snapshots.
+
+ Typically, only continuous integration servers are allowed to upload artifacts to the repository manager.
Review comment:
I personally view devs not being able to upload to the repository manager as an advantage, not a downside.
Having said that, I have clarified what to do if you prefer allowing devs to upload to the repository manager.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550285056
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
I agree that relying on default versions is not the best practice, and I also actively encourage specifying explicit versions. Unfortunately, in a large scale environment, we cannot instantly change all projects to not do it. People will use it because it is easy, or they don't know better, or they aren't that familiar with maven, or they don't even know that the maven-deploy-plugin is being used (since they never use it directly, only CI uses it).
I still think how to handle old maven-deploy-plugin versions needs to be mentioned for the guide to be most helpful to the target audience. The people reading the guide will probably have to deal with older projects using older versions of the maven-deploy-plugin, and (like me) cannot instantly upgrade thousands of poms even if they wanted to.
And the inability to instantly upgrade thousands of poms is also the reason we don't use `<distributionManagement>` at all in the pom, even with a custom property like @khmarbaise mentioned. The first time we rolled out this change, years ago, we needed to override the existing `<distributionManagement>` section in poms (that did not use a custom property), so we used the properties utilized by maven-deploy-plugin directly, and added properties supported by all versions of maven-deploy-plugin in use. Even if we started today, I'd still use the maven-deploy-plugin's properties, rather than custom properties just so there are no requirements in poms at all.
I favor centralizing all of the upload/download configuration in settings.xml files, without anything specific needed in the poms. In fact, I wish there was a `<distributionManagement>` section in the settings.xml file. Since downloads have first-class support in settings.xml files via the mirrors section, it makes logical sense that uploads should also have first-class support in settings.xml files.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] michael-o commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
michael-o commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550299955
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
Please file a JIRA issue with your feature request. In general project specific targets should be in the POM or inherited if they are general enough.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] michael-o commented on pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
michael-o commented on pull request #223:
URL: https://github.com/apache/maven-site/pull/223#issuecomment-752641357
>
>
> @slachiewicz , since [all the other guides](https://github.com/apache/maven-site/tree/master/content/apt/guides) are in apt, I'd rather keep this one in apt for consistency. I'm focused on the content for now. If it is indeed important to convert to markdown, I'd recommend a followup task to convert _all_ the guides to markdown, not just have this one as a one-off.
I fully agree here. We strive for consistency and content, rather than formats.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r549926035
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
Review comment:
Done
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on pull request #223:
URL: https://github.com/apache/maven-site/pull/223#issuecomment-752319875
@slachiewicz , since all the other guides are in apt, I'd rather keep this one in apt for consistency. I'm focused on the content for now. If it is indeed important to convert to markdown, I'd recommend a followup task to convert _all_ the guides to markdown, not just have this one as a one-off.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] michael-o commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
michael-o commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550214607
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
That's wrong. Relying on implicit versions is just wrong and encourage to explicitly ser versions. Advertising documentation for old versions makes life for us hard because we don't support old versions. We request to test with the most recent one. Everyone is obliged to set versions in a parent POM and stick to it. Since 2.8 is the last good version, I will still to this and not advertise anything older.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550308234
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
Filed https://issues.apache.org/jira/browse/MNG-7062
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr edited a comment on pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr edited a comment on pull request #223:
URL: https://github.com/apache/maven-site/pull/223#issuecomment-752319875
@slachiewicz , since [all the other guides](https://github.com/apache/maven-site/tree/master/content/apt/guides) are in apt, I'd rather keep this one in apt for consistency. I'm focused on the content for now. If it is indeed important to convert to markdown, I'd recommend a followup task to convert _all_ the guides to markdown, not just have this one as a one-off.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550376753
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
Review comment:
local/remote are the terms used by artifactory.
I just switched it to hosted/proxy in the latest commit, which are the terms used by nexus
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] michael-o commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
michael-o commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r549636990
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
Review comment:
Please capitalize Maven since it is a name.
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
Review comment:
Tell upfront that these properties are part of the Maven Deploy Plugin.
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
Igore everything below 2.8 and tell that this guide applies to 2.8+
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r549926099
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
Review comment:
I tried my best. Let me know if you have specific wording you would prefer.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550376789
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (Only needed if some projects are still using maven-deploy-plugin \< 2.8.
+ See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+ The following sections describe how to configure Maven clients to:
+
+ * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository.
+
+ * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the local repositories.
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by Maven projects in the organization should be downloaded
+ from the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the Maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's Maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by Maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the Maven <<<settings.xml>>> file.
+ When these properties are defined, the maven-deploy-plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}}
+ goal uses them instead of the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files
+ to determine where to upload artifacts.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files if/when the distribution locations need to change.
+
+ The ability to specify separate alternate deployment repositories for releases and snapshots
+ via the <<<altReleaseDeploymentRepository>>> and <<<altSnapshotDeploymentRepository>>> properties,
+ respectively, was added in maven-deploy-plugin 2.8.
+ To get the most out of the approach defined in this document, all projects should use maven-deploy-plugin \>=2.8.
+ If some projects are still using an older version of maven-deploy-plugin (\>=2.3 and \<2.8), then
+ specify a single alternate deployment repository via the <<<altDeploymentRepository>>> property
+ that points to a repository capable of containing both releases and snapshots.
+
+ Typically, only continuous integration servers are allowed to upload artifacts to the repository manager.
+ Therefore, these settings should only be specified in <<<settings.xml>>> files on continuous integration servers,
+ and should not be in <<<settings.xml>>> files on developer machines.
+
+ Example: To upload artifacts to one of the corporate repository manager's local repositories:
+
++-----+
+<settings>
+ ...
+ <profiles>
+ <profile>
+
+ <id>corp-repository-manager</id>
+
+ <properties>
+ <!--
+ For maven-deploy-plugin >= 2.8, deploy snapshots to this repository instead of the
+ distributionManagement snapshotRepository from project pom.xml files.
+ -->
+ <altSnapshotDeploymentRepository>corp::default::https://corp-repository-manager-host/maven-snapshots</altSnapshotDeploymentRepository>
+
+ <!--
+ For maven-deploy-plugin >= 2.8, deploy releases to this repository instead of the
+ distributionManagement repository from project pom.xml files.
+ -->
+ <altReleaseDeploymentRepository>corp::default::https://corp-repository-manager-host/maven-releases</altReleaseDeploymentRepository>
+
+ <!--
+ Only needed if some projects are still using maven-deploy-plugin >=2.3 and < 2.8,
+ which is the case if projects are using the default version of maven-deploy-plugin in maven 3.x.
+ For maven-deploy-plugin >=2.3 and < 2.8, deploy both releases and snapshots to this repository
+ instead of the repositories mentioned in distributionManagement from project pom.xml files.
+ -->
+ <altDeploymentRepository>corp::default::https://corp-repository-manager-host/maven-combined</altDeploymentRepository>
+ </properties>
+
+ <repositories>
+ <repository>
+ <id>corp</id>
+ <!--
+ This URL is overridden by the corp-repository-manager mirror above.
+ Some misbehaving tools might complain if they can't resolve the host specified here.
+ If you encounter this problem, use the same url as the corp-repository-manager mirror.
+ -->
+ <url>https://ignored</url>
+ <releases>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ <updatePolicy>always</updatePolicy>
+ </snapshots>
+ </repository>
+ </repositories>
+
+ <pluginRepositories>
+ <pluginRepository>
+ <id>corp</id>
+ <!--
+ This URL is overridden by the corp-repository-manager mirror above.
+ Some misbehaving tools might complain if they can't resolve the host specified here.
+ If you encounter this problem, use the same url as the corp-repository-manager mirror.
Review comment:
fixed
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
Review comment:
fixed
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] khmarbaise commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
khmarbaise commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550224261
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
I completely agree with @michael-o because not explicitly setting versions for all used plugins is simply the wrong way. Furthermore only using most recent versions in docs.
Apart from that. A simple solution is to use two properties (snapshot/release) (set in your settings.xml which you need anyway to access your repository manager) via your CI and using them in the distributionManagement configuration from within your corporate parent (which you should have; including the versions of plugins defined their apart from other defaults java versions etc). And you can go with the defaults (`mvn deploy`)...
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550376753
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
Review comment:
local/remote are the [terms used by artifactory](https://www.jfrog.com/confluence/display/JFROG/Repository+Management).
I just switched it to hosted/proxy in the latest commit, which are the [terms used by nexus](https://help.sonatype.com/repomanager2/configuration/managing-repositories)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] asfgit closed pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
asfgit closed pull request #223:
URL: https://github.com/apache/maven-site/pull/223
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] michael-o commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
michael-o commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550329282
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (Only needed if some projects are still using maven-deploy-plugin \< 2.8.
+ See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.)
+
+ Separate local repositories are generally used for releases and snapshots
Review comment:
Exactly here it gets confusing because Maven does not allow to split that. There is a feature request in JIRA for this.
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
Review comment:
Really local and not hosted? This could be confused with the Maven local repository (`-Dmaven.repo.local=....`).
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (Only needed if some projects are still using maven-deploy-plugin \< 2.8.
+ See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+ The following sections describe how to configure Maven clients to:
+
+ * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository.
+
+ * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the local repositories.
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by Maven projects in the organization should be downloaded
+ from the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the Maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's Maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by Maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the Maven <<<settings.xml>>> file.
+ When these properties are defined, the maven-deploy-plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}}
+ goal uses them instead of the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files
+ to determine where to upload artifacts.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files if/when the distribution locations need to change.
+
+ The ability to specify separate alternate deployment repositories for releases and snapshots
+ via the <<<altReleaseDeploymentRepository>>> and <<<altSnapshotDeploymentRepository>>> properties,
+ respectively, was added in maven-deploy-plugin 2.8.
+ To get the most out of the approach defined in this document, all projects should use maven-deploy-plugin \>=2.8.
+ If some projects are still using an older version of maven-deploy-plugin (\>=2.3 and \<2.8), then
+ specify a single alternate deployment repository via the <<<altDeploymentRepository>>> property
+ that points to a repository capable of containing both releases and snapshots.
+
+ Typically, only continuous integration servers are allowed to upload artifacts to the repository manager.
Review comment:
It is worthwhile to mention the downside that devs cannot upload anything anymore, neither snapshots nor releases?
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
Review comment:
an => a
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (Only needed if some projects are still using maven-deploy-plugin \< 2.8.
+ See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+ The following sections describe how to configure Maven clients to:
+
+ * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository.
+
+ * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the local repositories.
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by Maven projects in the organization should be downloaded
+ from the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the Maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's Maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by Maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the Maven <<<settings.xml>>> file.
+ When these properties are defined, the maven-deploy-plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}}
+ goal uses them instead of the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files
+ to determine where to upload artifacts.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files if/when the distribution locations need to change.
Review comment:
Please mention the downside that devs cannot upload anything anymore, neither snapshots nor releases.
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (Only needed if some projects are still using maven-deploy-plugin \< 2.8.
+ See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+ The following sections describe how to configure Maven clients to:
+
+ * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository.
+
+ * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the local repositories.
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by Maven projects in the organization should be downloaded
+ from the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the Maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's Maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by Maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the Maven <<<settings.xml>>> file.
+ When these properties are defined, the maven-deploy-plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}}
+ goal uses them instead of the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files
+ to determine where to upload artifacts.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<\<distributionManagement\>>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files if/when the distribution locations need to change.
+
+ The ability to specify separate alternate deployment repositories for releases and snapshots
+ via the <<<altReleaseDeploymentRepository>>> and <<<altSnapshotDeploymentRepository>>> properties,
+ respectively, was added in maven-deploy-plugin 2.8.
+ To get the most out of the approach defined in this document, all projects should use maven-deploy-plugin \>=2.8.
+ If some projects are still using an older version of maven-deploy-plugin (\>=2.3 and \<2.8), then
+ specify a single alternate deployment repository via the <<<altDeploymentRepository>>> property
+ that points to a repository capable of containing both releases and snapshots.
+
+ Typically, only continuous integration servers are allowed to upload artifacts to the repository manager.
+ Therefore, these settings should only be specified in <<<settings.xml>>> files on continuous integration servers,
+ and should not be in <<<settings.xml>>> files on developer machines.
+
+ Example: To upload artifacts to one of the corporate repository manager's local repositories:
+
++-----+
+<settings>
+ ...
+ <profiles>
+ <profile>
+
+ <id>corp-repository-manager</id>
+
+ <properties>
+ <!--
+ For maven-deploy-plugin >= 2.8, deploy snapshots to this repository instead of the
+ distributionManagement snapshotRepository from project pom.xml files.
+ -->
+ <altSnapshotDeploymentRepository>corp::default::https://corp-repository-manager-host/maven-snapshots</altSnapshotDeploymentRepository>
+
+ <!--
+ For maven-deploy-plugin >= 2.8, deploy releases to this repository instead of the
+ distributionManagement repository from project pom.xml files.
+ -->
+ <altReleaseDeploymentRepository>corp::default::https://corp-repository-manager-host/maven-releases</altReleaseDeploymentRepository>
+
+ <!--
+ Only needed if some projects are still using maven-deploy-plugin >=2.3 and < 2.8,
+ which is the case if projects are using the default version of maven-deploy-plugin in maven 3.x.
+ For maven-deploy-plugin >=2.3 and < 2.8, deploy both releases and snapshots to this repository
+ instead of the repositories mentioned in distributionManagement from project pom.xml files.
+ -->
+ <altDeploymentRepository>corp::default::https://corp-repository-manager-host/maven-combined</altDeploymentRepository>
+ </properties>
+
+ <repositories>
+ <repository>
+ <id>corp</id>
+ <!--
+ This URL is overridden by the corp-repository-manager mirror above.
+ Some misbehaving tools might complain if they can't resolve the host specified here.
+ If you encounter this problem, use the same url as the corp-repository-manager mirror.
+ -->
+ <url>https://ignored</url>
+ <releases>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ <updatePolicy>always</updatePolicy>
+ </snapshots>
+ </repository>
+ </repositories>
+
+ <pluginRepositories>
+ <pluginRepository>
+ <id>corp</id>
+ <!--
+ This URL is overridden by the corp-repository-manager mirror above.
+ Some misbehaving tools might complain if they can't resolve the host specified here.
+ If you encounter this problem, use the same url as the corp-repository-manager mirror.
Review comment:
url => URL
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] michael-o commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
michael-o commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r550452528
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,241 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization with hundreds/thousands of Maven projects.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in Maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
Review comment:
Thanks, I am aware of that, but want to avoid confusion from a viewer's PoV. See https://issues.apache.org/jira/browse/MNG-3655.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
[GitHub] [maven-site] philsttr commented on a change in pull request #223: [MNGSITE-438] Add guide for Large Scale Centralized Deployments
Posted by GitBox <gi...@apache.org>.
philsttr commented on a change in pull request #223:
URL: https://github.com/apache/maven-site/pull/223#discussion_r549927249
##########
File path: content/apt/guides/mini/guide-large-scale-centralized-deployments.apt
##########
@@ -0,0 +1,230 @@
+ ------
+ Guide to Large Scale Centralized Deployments
+ ------
+ Phil Clay
+ ------
+ 2021-01-01
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Guide to Large Scale Centralized Deployments
+
+ This guide covers an simple optimized approach to using a
+ {{{../../repository-management.html}repository manager}}
+ in a large organization.
+
+ The pillars of this approach are:
+
+ [[1]] Use a centralized {{{../../repository-management.html}repository manager}}.
+
+ * Maven clients should download needed artifacts from the repository manager.
+
+ * Maven clients should upload proprietary artifacts to the repository manager.
+
+ [[2]] Configure the location to download/upload artifacts in maven <<<settings.xml>>> files,
+ rather than in <<<pom.xml>>> files.
+
+ [[3]] Centrally manage the <<<settings.xml>>> files, and distribute them via automation.
+
+
+* {Repository Manager Layout}
+
+ Repository managers generally have at least three types of repositories:
+
+ [local] contains local artifacts uploaded to the repository manager
+
+ [remote] proxies a remote repository and caches artifacts
+
+ [virtual] aggregates several repositories into one
+
+
+ The simplest way to organize repositories within a repository manager is
+ to have a single virtual repository that aggregates:
+
+ * a remote repository for each public repository to mirror. (For example: Maven Central)
+
+ * a local repository for releases
+
+ * a local repository for snapshots
+
+ * a local repository that can contain both releases and snapshots
+ (see {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for why this repository is needed)
+
+ Separate local repositories are generally used for releases and snapshots
+ due to the need for different artifact retention policies.
+
+
+* {Managing Downloads from the Repository Manager}
+
+ All artifacts used by maven projects in the organization should be downloaded
+ via the single virtual repository of the repository manager.
+
+ Maven can be instructed to download artifacts from the repository manager's virtual repository
+ by defining a mirror in the maven <<<settings.xml>>> file as described in the
+ {{{./guide-mirror-settings.html}Guide to Mirror Settings}}.
+
+ Example: To download artifacts from the corporate repository manager's <<<maven-virtual>>> repository:
+
++-----+
+<settings>
+ ...
+ <mirrors>
+ <!-- Mirror all external repositories via the Corporate Repository Manager's maven virtual repository -->
+ <mirror>
+ <id>corp-repository-manager</id>
+ <name>Corporate Repository Manager</name>
+ <mirrorOf>external:*</mirrorOf>
+ <url>https://corp-repository-manager-host/maven-virtual</url>
+ </mirror>
+ </mirrors>
+ ...
+</settings>
++-----+
+
+* {Managing Uploads to the Repository Manager}
+
+ All proprietary artifacts produced by maven projects in the organization should be uploaded
+ to the repository manager's local repositories.
+
+ The {{{../../plugins/maven-deploy-plugin}maven-deploy-plugin}} can be instructed to upload artifacts
+ to the repository manager's repositories by defining the <<<alt*DeploymentRepository>>> properties
+ in the maven <<<settings.xml>>> file.
+
+ Defining the upload destination of artifacts in <<<settings.xml>>> files rather than
+ in the <<<distributionManagement>>> section of <<<pom.xml>>> files allows the destinations
+ to be centrally managed, which simplifies maintenance if the destinations need to change.
+ In other words, rather than changing a huge number of <<<pom.xml>>> files,
+ you just need to change {{{Settings_File_Locations}relatively few}}
+ <<<settings.xml>>> files when the distribution locations need to change.
+
+ The ability to specify a <single> alternate deployment repository via the <<<altDeploymentRepository>>>
+ property was added in maven-deploy-plugin 2.3.
+ This single alternate deployment repository is used for both releases and snapshots.
+ Therefore, a repository capable of hosting release and snapshots artifacts must exist on the repository manager
+ when using maven-deploy-plugin \>=2.3 and \<2.8.
Review comment:
Because Maven 3.6 still uses maven-deploy-plugin 2.7 as the default version, large organizations with many Maven projects are likely to still be using maven-deploy-plugin 2.7. Even in my own organization, where we've been using this approach for years, we still have projects on maven-deploy-plugin 2.7 (even new projects).
I think the information on how to configure the old maven-deploy-plugin is critical to the target audience of this guide. Maybe in a few years, when the vast majority of projects are upgraded to maven 4.x, where the default version of maven-deploy-plugin has been bumped to 3.x, this information can be removed.
Having said that, I've reworded the sections on the maven-deploy-plugin versions to emphasize usage of 2.8.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org