| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| ~~ 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. |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| -------------------- |
| Publishing this site |
| -------------------- |
| |
| How to publish the Rat website |
| |
| The {{{https://creadur.apache.org}Apache Creadur}} project, the community |
| that develops {{{https://creadur.apache.org/rat}Apache Rat}}, |
| hosts its website on the |
| {{{https://www.apache.org/dev/cms.html}ASF Content Management System}}. |
| {{{https://maven.apache.org}Apache Maven}} builds Rat, and generates this |
| subsite. Here's (one way) to work with these systems. |
| |
| * Developing Content |
| |
| Build and generate the site using Maven the usual way. A plain 'site' does not generate a fully complete page, thus: |
| |
| +------------------------------------------+ |
| mvn clean site site:stage |
| +------------------------------------------+ |
| |
| This will generate a complete page under 'target/staging'. |
| |
| Make your changes to the <<<site.xml>>> and/or <<<.apt>>> files then launch |
| a server on <<<localhost:8080>>> using |
| |
| +------------------------------------------+ |
| mvn site:run |
| +------------------------------------------+ |
| |
| Review {{{http://localhost:8080}<<<localhost:8080>>>}} using a browser, and do more edits. |
| You'll see your changes as soon as you refresh the page. |
| |
| * Committing and Reviewing Content |
| |
| As soon as your changes look okay locally on <<<localhost:8080>>>, commit them. |
| {{{https://ci.apache.org/buildbot.html}Buildbot}} will automatically |
| notice the commit and create a staging site to look at |
| {{{https://builds.apache.org/view/A-D/view/Creadur/} https://builds.apache.org/view/A-D/view/Creadur/}} |
| which is always up to date (within a couple of minutes of any commit). |
| |
| Need to make changes? No problem - go back and repeat the cycle as often as you like. |
| |
| Happy with changes and ready to go live? Then read on... |
| |
| * Publishing the Site |
| |
| The publishing process updates the main site with any changes committed since the last |
| time the site was published. |
| |
| Publishing is a multi-stage process with a mixture of automated |
| and manual processing. End to end, the process is slow - perhaps |
| taking 30 minutes but close supervision is not required. |
| |
| ** Deploy the Site locally |
| |
| Rat declares a local directory (<<<stage>>>) for Maven |
| site deployments. To avoid excessive numbers of commits, the |
| local directory needs to remain ignored by <<<subversion>>>. |
| As well as being the target for <<<mvn site-deploy>>>, this is also |
| the origin for publication. |
| |
| Triggering the automated publication pipeline is a two phase process: |
| Maven needs to deploy the latest site locally and then |
| <<<scm-publish>>> pushes this content into version control. |
| |
| If you prefer to be prompted to type your subversion passphrase, edit |
| <<<~/.scm/svn-settings.xml>>> to include |
| |
| +------------------------------------------+ |
| <svn-settings> |
| ... |
| <useNonInteractive>false</useNonInteractive> |
| <useAuthCache>false</useAuthCache> |
| ... |
| </svn-settings> |
| +------------------------------------------+ |
| |
| Run both steps together using |
| |
| +------------------------------------------+ |
| |
| mvn site-deploy scm-publish:publish-scm |
| |
| +------------------------------------------+ |
| |
| Publication is slow, and the plugin may wait silently for up to |
| 30 minutes - so please allow the build enough time to complete. |
| |
| ** Automated Staging of the Site |
| |
| The content committed by the Maven <<<scm-publish>>> plugin |
| triggers a staging build on |
| {{{https://ci.apache.org/}<<<https://ci.apache.org/>>>}}. To |
| follow its progress, open the |
| {{{https://ci.apache.org/builders/creadur-site-staging}creadur |
| site builder}}. |
| |
| When this builds has completed successfully, review the content |
| staged on |
| {{{https://creadur.staging.apache.org/rat/index.html} |
| <<<https://creadur.staging.apache.org/rat/index.html>>>}}. If |
| this looks fine then publish the staged content using the |
| {{{https://www.apache.org/dev/cms.html}ASF Content Management System}}. |
| |
| Propagating the content to {{{https://creadur.apache.org/rat}production}} may take a brief while (maybe |
| 30 seconds) so please be patient a little longer. |
| |
| * Troubleshooting |
| |
| * If you have issues with 'mvn site' failing try running 'mvn clean' then 'mvn install' before going back and running 'mvn site' again. |
| |
| * If you experience an Out of Memory error <<java.lang.OutOfMemoryError: Java heap space>> when running 'mvn site' try setting 'export MAVEN_OPTS=-Xmx512m' |
| or for Windows 'set MAVEN_OPTS=-Xmx512m' first on the command line (or in your profile) and then try 'mvn site' again. |