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