blob: 46e7fe4574d0832cb1238bd70e401325e152f310 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/apt/site-publish.apt at 2024-05-07
| Rendered using Apache Maven Default Skin
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" />
<title>Apache Rat&trade; &#x2013; Publishing this site (deprecated)</title>
<link rel="stylesheet" href="./css/maven-base.css" />
<link rel="stylesheet" href="./css/maven-theme.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<link href="https://creadur.apache.org/font/matesc.css" type="text/css" rel="stylesheet" />
</head>
<body class="composite">
<div id="banner">
<a href="https://www.apache.org/" id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png" alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xleft">
<span id="publishDate">Last Published: 2024-05-07</span>
| <span id="projectVersion">Version: 0.17-SNAPSHOT</span>
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a> &gt;
<a href="https://creadur.apache.org/" class="externalLink" title="Creadur">Creadur</a> &gt;
<a href="https://creadur.apache.org/rat/" class="externalLink" title="Rat">Rat</a> &gt;
Publishing this site (deprecated)
</div>
<div class="xright"> </div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>Apache Ratâ„¢</h5>
<ul>
<li class="none"><a href="index.html" title="Introducing Rat">Introducing Rat</a></li>
<li class="none"><a href="apidocs/index.html" title="Javadocs">Javadocs</a></li>
<li class="none"><a href="download_rat.cgi" title="Downloads">Downloads</a></li>
<li class="none"><a href="RELEASE_NOTES.txt" title="Changes">Changes</a></li>
</ul>
<h5>Running Rat</h5>
<ul>
<li class="none"><a href="apache-rat/index.html" title="From The Command Line">From The Command Line</a></li>
<li class="none"><a href="apache-rat-tasks/index.html" title="With Ant">With Ant</a></li>
<li class="none"><a href="apache-rat-plugin/index.html" title="With Maven">With Maven</a></li>
</ul>
<h5>Apache Creadurâ„¢</h5>
<ul>
<li class="none"><a href="https://creadur.apache.org" class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li>
<li class="none"><a href="https://creadur.apache.org/tentacles" class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li>
<li class="none"><a href="https://creadur.apache.org/whisker" class="externalLink" title="Apache Whisker">Apache Whisker</a></li>
<li class="none"><a href="https://www.apache.org/security/" class="externalLink" title="Security">Security</a></li>
<li class="none"><a href="https://www.apache.org/licenses/" class="externalLink" title="License">License</a></li>
<li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html" class="externalLink" title="Privacy">Privacy</a></li>
<li class="none"><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a></li>
<li class="none"><a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a></li>
</ul>
<h5>The Apache Software Foundation</h5>
<ul>
<li class="none"><a href="https://www.apache.org/foundation" class="externalLink" title="About the Foundation">About the Foundation</a></li>
<li class="none"><a href="https://projects.apache.org" class="externalLink" title="The projects">The projects</a></li>
<li class="none"><a href="https://people.apache.org" class="externalLink" title="The people">The people</a></li>
<li class="none"><a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How we work">How we work</a></li>
<li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history" class="externalLink" title="Our history">Our history</a></li>
<li class="none"><a href="https://blogs.apache.org/foundation/" class="externalLink" title="News">News</a></li>
</ul>
<h5>Contribute</h5>
<ul>
<li class="none"><a href="https://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved">Get Involved</a></li>
</ul>
<h5>Committer Info</h5>
<ul>
<li class="none"><a href="https://www.apache.org/dev/committers.html" class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li>
<li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html" class="externalLink" title="New Committers Guide">New Committers Guide</a></li>
<li class="none"><strong>Howto publish this site</strong></li>
<li class="none"><a href="https://community.apache.org/" class="externalLink" title="Community">Community</a></li>
<li class="none"><a href="https://www.apache.org/legal/" class="externalLink" title="Legal">Legal</a></li>
<li class="none"><a href="https://www.apache.org/foundation/marks/" class="externalLink" title="Branding">Branding</a></li>
<li class="none"><a href="https://www.apache.org/press/" class="externalLink" title="Media Relations">Media Relations</a></li>
</ul>
<h5>Modules</h5>
<ul>
<li class="none"><a href="apache-rat-core/index.html" title="Apache Creadur Rat::Core">Apache Creadur Rat::Core</a></li>
<li class="none"><a href="apache-rat-plugin/index.html" title="Apache Creadur Rat::Plugin4Maven">Apache Creadur Rat::Plugin4Maven</a></li>
<li class="none"><a href="apache-rat-tasks/index.html" title="Apache Creadur Rat::Tasks4Ant">Apache Creadur Rat::Tasks4Ant</a></li>
<li class="none"><a href="apache-rat/index.html" title="Apache Creadur Rat::Command Line">Apache Creadur Rat::Command Line</a></li>
<li class="none"><a href="apache-rat-tools/index.html" title="Apache Creadur Rat::Tools">Apache Creadur Rat::Tools</a></li>
</ul>
<h5>Project Documentation</h5>
<ul>
<li class="collapsed"><a href="project-info.html" title="Project Information">Project Information</a></li>
<li class="collapsed"><a href="project-reports.html" title="Project Reports">Project Reports</a></li>
</ul>
<a href="https://maven.apache.org/" title="Maven" class="poweredBy">
<img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<section>
<h2><a name="How_to_publish_the_Rat_website"></a>How to publish the Rat website</h2>
<p>The <a class="externalLink" href="https://creadur.apache.org">Apache Creadur</a> project, the community that develops <a class="externalLink" href="https://creadur.apache.org/rat">Apache Rat</a>, hosts its website on the <a class="externalLink" href="https://www.apache.org/dev/cms.html">ASF Content Management System</a>. <a class="externalLink" href="https://maven.apache.org">Apache Maven</a> builds Rat, and generates this subsite. Here's (one way) to work with these systems.</p><section>
<h3><a name="Developing_Content"></a>Developing Content</h3>
<p>Build and generate the site using Maven the usual way. A plain 'site' does not generate a fully complete page, thus:</p>
<div class="source">
<pre>mvn clean site site:stage</pre></div>
<p>This will generate a complete page under 'target/staging'.</p>
<p>Make your changes to the <code>site.xml</code> and/or <code>.apt</code> files then launch a server on <code>localhost:8080</code> using</p>
<div class="source">
<pre> mvn site:run</pre></div>
<p>Review <a class="externalLink" href="http://localhost:8080"><code>localhost:8080</code></a> using a browser, and do more edits. You'll see your changes as soon as you refresh the page.</p></section><section>
<h3><a name="Committing_and_Reviewing_Content"></a>Committing and Reviewing Content</h3>
<p>As soon as your changes look okay locally on <code>localhost:8080</code>, commit them. <a class="externalLink" href="https://ci.apache.org/buildbot.html">Buildbot</a> will automatically notice the commit and create a staging site to look at <a class="externalLink" href="https://builds.apache.org/view/A-D/view/Creadur/"> https://builds.apache.org/view/A-D/view/Creadur/</a> which is always up to date (within a couple of minutes of any commit).</p>
<p>Need to make changes? No problem - go back and repeat the cycle as often as you like.</p>
<p>Happy with changes and ready to go live? Then read on...</p></section><section>
<h3><a name="Publishing_the_Site"></a>Publishing the Site</h3>
<p>The publishing process updates the main site with any changes committed since the last time the site was published.</p>
<p>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.</p><section>
<h4><a name="Deploy_the_Site_locally"></a>Deploy the Site locally</h4>
<p>Rat declares a local directory (<code>stage</code>) for Maven site deployments. To avoid excessive numbers of commits, the local directory needs to remain ignored by <code>subversion</code>. As well as being the target for <code>mvn site-deploy</code>, this is also the origin for publication.</p>
<p>Triggering the automated publication pipeline is a two phase process: Maven needs to deploy the latest site locally and then <code>scm-publish</code> pushes this content into version control.</p>
<p>If you prefer to be prompted to type your subversion passphrase, edit <code>~/.scm/svn-settings.xml</code> to include</p>
<div class="source">
<pre>&lt;svn-settings&gt;
...
&lt;useNonInteractive&gt;false&lt;/useNonInteractive&gt;
&lt;useAuthCache&gt;false&lt;/useAuthCache&gt;
...
&lt;/svn-settings&gt;</pre></div>
<p>Run both steps together using</p>
<div class="source">
<pre>
mvn site-deploy scm-publish:publish-scm
</pre></div>
<p>Publication is slow, and the plugin may wait silently for up to 30 minutes - so please allow the build enough time to complete.</p></section><section>
<h4><a name="Automated_Staging_of_the_Site"></a>Automated Staging of the Site</h4>
<p>The content committed by the Maven <code>scm-publish</code> plugin triggers a staging build on <a class="externalLink" href="https://ci.apache.org/"><code>https://ci.apache.org/</code></a>. To follow its progress, open the <a class="externalLink" href="https://ci.apache.org/builders/creadur-site-staging">creadur site builder</a>.</p>
<p>When this builds has completed successfully, review the content staged on <a class="externalLink" href="https://creadur.staging.apache.org/rat/index.html"> <code>https://creadur.staging.apache.org/rat/index.html</code></a>. If this looks fine then publish the staged content using the <a class="externalLink" href="https://www.apache.org/dev/cms.html">ASF Content Management System</a>.</p>
<p>Propagating the content to <a class="externalLink" href="https://creadur.apache.org/rat">production</a> may take a brief while (maybe 30 seconds) so please be patient a little longer.</p></section></section><section>
<h3><a name="Troubleshooting"></a>Troubleshooting</h3>
<ul>
<li>If you have issues with 'mvn site' failing try running 'mvn clean' then 'mvn install' before going back and running 'mvn site' again.</li>
<li>If you experience an Out of Memory error <b>java.lang.OutOfMemoryError: Java heap space</b> 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.</li></ul></section></section>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">
Copyright &copy; 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks
of The Apache Software Foundation.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>