src/site/apt/index.apt.vm

 ------
 Introduction
 ------
 Benson Margulies
 ------
 2013-07-22
 ------

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

${project.name}

    The maven-scm-publish-plugin is a utility plugin to allow publishing Maven
    website to any supported SCM.
    The primary goal was to have an utility plugin to allow Apache projects
    to publish Maven websites via the ASF svnpubsub system

    In addition to SCM operations, it takes care to fix newline inconsistencies
    generated by <<<maven-site-plugin>>> (see {{{https://jira.codehaus.org/browse/MSITE-121}MSITE-121}}),
    which prevents simple content import to SCM.

    The plugin has been tested with git scm too and by example can push content for github pages too.


* Implementation

    The plugin works from staged website by default (see {{{./publish-scm-mojo.html#content}<<<content>>> parameter}}).

    It first checks out the contents of a directory from
    the SCM (see {{{./publish-scm-mojo.html#pubScmUrl}<<<pubSubUrl>>> parameter}}) into
    <<<target/scmpublish-checkout>>> by default (see {{{./publish-scm-mojo.html#checkoutDirectory}<<<checkoutDirectory>>> parameter}}).

    Then locally staged content is applied to the check-out, issuing
    appropriate SCM commands to add and delete entries, followed by a
    checkin.

    The <<scmpublish.dryRun>> parameter to the plugin avoids all
    SCM operations, and simply logs out the added, deleted,
    and changed files.

    The <<scmpublish.skipCheckin>> parameter omits the final checkin.
    This allows you to visit <<<target/scmpublish-checkout>>>, and validate
    its contents before submitting to the SCM.

* Publishing any content to SCM

    Even without any pom.xml/Maven project, you can update SCM content with
    a local content:

+-------+
mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:... -Dscmpublish.content=...path-to-content...
+-------+

    SCM content will be checked-out to a temporary directory, then local content will
    be applied to the check-out, before it is checked-in back.

    See {{{./examples/importing-maven-site.html}maven.apache.org content import script}} for an
    example.

    <<See {{{./various-tips.html}Some Tips}}.>>

* Known Limitations

    There are 2 known limitations:
    
    * For svn the plugin can create the initial SCM directory if it does not exist. But for git by example if you use a branch,
    the branch won't be created, you have to create it manually.

    * the plugin works well for multi-module websites publishing to a complete directory:
    you just need to publish <<<mvn site:stage>>> content. But if one module does not publish
    its content to the same directory (like Surefire or Enforcer, which have a
    base directory and one plugin in <<</plugins/>>>), this staging area can't be simply imported.

    []

* Future Dreams

    Ideally, scm urls would be supported in <<<\<distributionManagement>>>> section of the POM, then
    publishing would simply be <<<mvn site-deploy>>>, without any problems for non-flat multi-modules
    sites.

    To reach such a dream, there are some steps:

    * fix inconsistent newlines generated by <<<maven-site-plugin>>> (caused by site.vm template and
      resources taken from skin jar without fixing newlines): {{{https://jira.codehaus.org/browse/MSITE-121}MSITE-121}}
      is fixed in (future) maven-site-plugin 3.4,

    * improve {{{/wagon/wagon-providers/wagon-scm/}<<<wagon-scm>>>}} to put a whole directory content
      in one commit, and not with one commit per file.

    []

    Then this plugin will be outdated, replaced by natural <<<maven-site-plugin:deploy>>> goal.