| ------ |
| Various Tips |
| ------ |
| Olivier Lamy |
| ------ |
| 2012-09-04 |
| ------ |
| |
| ~~ 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 |
| |
| Various tips for using this plugin |
| |
| * URL format |
| |
| You must use a scm url format: |
| |
| +----------------+ |
| scm:<scm_provider><delimiter><provider_specific_part> |
| +----------------+ |
| |
| Example for svn: <<<scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/>>> |
| |
| And configure is as it: |
| |
| +----------------+ |
| <distributionManagement> |
| <site> |
| <id>site_id</id> |
| <url>scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/</url> |
| </site> |
| </distributionManagement> |
| +----------------+ |
| |
| <<NOTE>>: with svn, if the remote url doesn't exist, it will be created. |
| |
| * Git branch |
| |
| To use Git branch (for example: {{{https://help.github.com/articles/user-organization-and-project-pages/}GitHub <<<gh-pages>>>}}) |
| |
| +----------------+ |
| <distributionManagement> |
| <site> |
| <id>site_id</id> |
| <url>${project.scm.developerConnection}</url><!-- or scm:git:ssh://git@github.com/username/tomcat-foo-artifact.git --> |
| </site> |
| </distributionManagement> |
| ... |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-scm-publish-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <scmBranch>gh-pages</scmBranch> |
| </configuration> |
| </plugin> |
| +----------------+ |
| |
| <<Initial creation of the branch has to be done manually>>, as a Git orphan branch: |
| |
| 1. <<<git checkout --orphan gh-pages>>> to create the branch locally, |
| |
| 2. <<<rm .git/index ; git clean -fdx>>> to clean the branch content and let it empy, |
| |
| 3. copy an initial site content, |
| |
| 4. commit and push: <<<git add *>>>, <<<git commit -m "initial site content">>>, <<<git push>>> |
| |
| [] |
| |
| * Improving SCM Checkout Performance |
| |
| By default, a complete checkout is done. You can configure the plugin to try update rather than a full checkout/clone |
| |
| +----------------+ |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-scm-publish-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <tryUpdate>true</tryUpdate> |
| </configuration> |
| </plugin> |
| +----------------+ |
| |
| By default, the scm content is checked-out/cloned to <<<$\{project.build.directory}/scmpublish-checkout>>>, so when running <<<mvn clean>>>, |
| all the content is deleted. You can configure a path to your machine to avoid full checkout. |
| A recommended way is to use a property with a default value that your colleague will be able to override in their settings. |
| |
| +----------------+ |
| <properties> |
| ... |
| <!-- override in your settings --> |
| <siteMainDirectory>${user.home}</siteMainDirectory> |
| <scmPubCheckoutDirectory>\${siteMainDirectory}/my-site-content-scm</scmPubCheckoutDirectory> |
| ... |
| </properties> |
| |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-scm-publish-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <checkoutDirectory>${scmPubCheckoutDirectory}</checkoutDirectory> |
| <tryUpdate>true</tryUpdate> |
| </configuration> |
| </plugin> |
| +----------------+ |
| |
| |
| * Using alternate scm provider |
| |
| You can use svnjava rather than default svn cli if you use a machine without svn cli. |
| |
| +----------------+ |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-scm-publish-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <providerImplementations> |
| <svn>javasvn</svn> |
| </providerImplementations> |
| </configuration> |
| <dependencies> |
| <dependency> |
| <groupId>com.google.code.maven-scm-provider-svnjava</groupId> |
| <artifactId>maven-scm-provider-svnjava</artifactId> |
| <version>${maven-scm-provider-svnjava-version}</version> |
| </dependency> |
| <dependency> |
| <groupId>org.tmatesoft.svnkit</groupId> |
| <artifactId>svnkit</artifactId> |
| <version>${svnkit-version}</version> |
| </dependency> |
| </dependencies> |
| </plugin> |
| +----------------+ |