[MDEPOY-250] document network issues workaround found by PLC4X
diff --git a/src/site/apt/examples/deploy-network-issues.apt b/src/site/apt/examples/deploy-network-issues.apt
new file mode 100644
index 0000000..059f4eb
--- /dev/null
+++ b/src/site/apt/examples/deploy-network-issues.apt
@@ -0,0 +1,123 @@
+ ------
+ Deploying With Network Issues
+ ------
+ Hervé Boutemy
+ ------
+ 2019-01-20
+ ------
+
+~~ 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
+
+Deploying With Network Issues
+
+ Sometimes, network quality from building machine to the remote repository is not perfect.
+ Of course, improving the network would be the best solution, but it is not always possible.
+
+ There are a few strategies to work around the network issue.
+
+* Configuring Multiple Tries
+
+ Deploy plugin provides {{{../deploy-mojo.html#retryFailedDeploymentCount}<<<retryFailedDeploymentCount>>> parameter}}
+ to retry deployment multiple times before giving up and returning a failure for the <<<deploy>>> goal:
+
++----+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-deploy-plugin</artifactId>
+ <configuration>
+ <retryFailedDeploymentCount>3</retryFailedDeploymentCount>
+ <configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++----+
+
+* Deploying to a Local Staging Directory
+
+ When the network is really not consistent, a deeper strategy is to deploy in 2 steps:
+
+ 1. <<<deploy>>> to a local <<<file:./target/staging-deploy>>> directory during the build,
+
+ 2. then copy from the local area to the target remote repository, retrying as much as necessary.
+
+ []
+
+** Deploying to a Local Directory
+
+ Deploying to a local directory can be done from command line, without changing POM, using
+ {{{../deploy-mojo.html#altDeploymentRepository}<<<altDeploymentRepository>>> parameter}}:
+
++----+
+mvn deploy -DaltDeploymentRepository=local::file:./target/staging-deploy
++----+
+
+ Notice: with maven-deploy-plugin 2.x, the parameter format was <<<local::default::file:./target/staging-deploy>>>
+
+ Of course, if you want can configure the repository in your <<<pom.xml>>> if you want to go from a temporary strategy
+ to the general strategy.
+
+** Copying from Local Directory to Target Remote Repository
+
+ <<<wagon-maven-plugin>>>'s {{{http://www.mojohaus.org/wagon-maven-plugin/merge-maven-repos-mojo.html}<<<merge-maven-repos>>> goal}}
+ provides a mechanism to copy from one remote repository to the other, while merging repository metadata.
+
+ <<<wagon-maven-plugin>>>'s {{{http://www.mojohaus.org/wagon-maven-plugin/upload-mojo.html}<<<upload>>> goal}}
+ will do the same without taking care of repository metadata: use it if you have an empty repository as target,
+ like a staging repository provided by a repository manager.
+
+ It can be invoked fully from command line (renaming <<<-Dwagon.>>> with <<<wagon.targetId>>> when
+ {{{https://github.com/mojohaus/wagon-maven-plugin/pull/26}2.0.1 will be released}}):
+
++----+
+mvn org.codehaus.mojo:wagon-maven-plugin:2.0.0:merge-maven-repos \
+ -Dwagon.source=file:./target/staging-deploy \
+ -Dwagon.target=https://... \
+ -Dwagon.=id
++----+
+
+ or more simply with <<<mvn wagon:merge-maven-repos>>> with configuration in <<<pom.xml>>>:
+
++----+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>wagon-maven-plugin</artifactId>
+ <version>2.0.0</version>
+ <configuration>
+ <source>file:./target/staging-deploy</source>
+ <target>https://...</target>
+ <targetId>id</targetId>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++----+
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
index c5e814e..c91364d 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -114,6 +114,8 @@
* {{{./examples/deploy-ssh-external.html}Deployment with external SSH}}
+ * {{{./examples/deploy-network-issues.html}Workarounds when there are network issues}}
+
[]
<File Deployment:>
diff --git a/src/site/apt/project-deployment.apt b/src/site/apt/project-deployment.apt
index 39d3390..e74a029 100644
--- a/src/site/apt/project-deployment.apt
+++ b/src/site/apt/project-deployment.apt
@@ -34,4 +34,6 @@
* {{{./examples/deploy-ssh-external.html}Deployment with external SSH}}
+ * {{{./examples/deploy-network-issues.html}Workarounds when there are network issues}}
+
[]
\ No newline at end of file
