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 {{{https://infra.apache.org/project-site.html#tools}ASF svnpubsub system}}.

    In addition to SCM operations, it takes care to fix newline inconsistencies
    generated by <<<maven-site-plugin>>> (see {{{https://issues.apache.org/jira/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
    {{{./various-tips.html#Git_branch}push content for GitHub Pages}}.


* 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
    check-in.

    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:<scm-provider>... -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 Subversion, 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 {{{./various-tips.html#Git_branch}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://issues.apache.org/jira/browse/MSITE-121}MSITE-121}}
      is fixed in 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 would be outdated, replaced by natural <<<maven-site-plugin:deploy>>> goal.