src/site/apt/various-tips.apt.vm

 ------
 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>
+----------------+