Google Git
Sign in
apache / streams / refs/heads/asf-site / . / website.html
blob: 66088f42480397f2a8056a89c2853b96f63a5802 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-04-02
| Rendered using Apache Maven Fluido Skin 1.5
-->
<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="Date-Revision-yyyymmdd" content="20180402" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Streams &#x2013; Website Management</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.5.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/apache-maven-fluido-1.5.min.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-77087101-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body class="topBarEnabled">
<a href="https://github.com/apache/streams">
<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png"
alt="Fork me on GitHub">
</a>
<div id="topbar" class="navbar navbar-fixed-top navbar-inverse">
<div class="navbar-inner">
<div class="container"><div class="nav-collapse">
<ul class="nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="index.html" title="Overview">Overview</a>
</li>
<li> <a href="architecture.html" title="Architecture">Architecture</a>
</li>
<li> <a href="concepts.html" title="Concepts">Concepts</a>
</li>
<li> <a href="downloads.html" title="Downloads">Downloads</a>
</li>
<li> <a href="streams-examples/index.html" title="Examples">Examples</a>
</li>
<li> <a href="faq.html" title="Frequently Asked Questions">Frequently Asked Questions</a>
</li>
<li> <a href="modules.html" title="Modules">Modules</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="install/java.html" title="Install Java">Install Java</a>
</li>
<li> <a href="install/docker.html" title="Install Docker">Install Docker</a>
</li>
<li> <a href="install/sbt.html" title="Install SBT">Install SBT</a>
</li>
<li class="dropdown-submenu">
<a href="" title="Credentials">Credentials</a>
<ul class="dropdown-menu">
<li> <a href="credentials/twitter.html" title="Twitter">Twitter</a>
</li>
</ul>
</li>
<li class="dropdown-submenu">
<a href="" title="Services">Services</a>
<ul class="dropdown-menu">
<li> <a href="services/cassandra.html" title="Cassandra">Cassandra</a>
</li>
<li> <a href="services/elasticsearch.html" title="Elasticsearch">Elasticsearch</a>
</li>
<li> <a href="services/mongo.html" title="Mongo">Mongo</a>
</li>
<li> <a href="services/neo4j.html" title="Neo4j">Neo4j</a>
</li>
<li> <a href="services/riak.html" title="Riak">Riak</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="install/git.html" title="Install Git">Install Git</a>
</li>
<li> <a href="install/maven.html" title="Install Maven">Install Maven</a>
</li>
<li> <a href="changelog.html" title="Changelog">Changelog</a>
</li>
<li> <a href="release-setup.html" title="Release Setup">Release Setup</a>
</li>
<li> <a href="release.html" title="Release Process">Release Process</a>
</li>
<li> <a href="website.html" title="Website Management">Website Management</a>
</li>
<li> <a href="code-conventions.html" title="Coding Conventions">Coding Conventions</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Reports <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="dropdown-submenu">
<a href="project-info.html" title="Project Information">Project Information</a>
<ul class="dropdown-menu">
<li> <a href="index.html" title="About">About</a>
</li>
<li> <a href="modules.html" title="Project Modules">Project Modules</a>
</li>
<li> <a href="license.html" title="Licenses">Licenses</a>
</li>
<li> <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li> <a href="team-list.html" title="Team">Team</a>
</li>
<li> <a href="source-repository.html" title="Source Code Management">Source Code Management</a>
</li>
<li> <a href="issue-tracking.html" title="Issue Management">Issue Management</a>
</li>
<li> <a href="dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li> <a href="dependency-info.html" title="Dependency Information">Dependency Information</a>
</li>
<li> <a href="dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li> <a href="distribution-management.html" title="Distribution Management">Distribution Management</a>
</li>
<li> <a href="plugin-management.html" title="Plugin Management">Plugin Management</a>
</li>
</ul>
</li>
<li class="dropdown-submenu">
<a href="project-reports.html" title="Project Reports">Project Reports</a>
<ul class="dropdown-menu">
<li> <a href="checkstyle.html" title="Checkstyle">Checkstyle</a>
</li>
<li> <a href="checkstyle-aggregate.html" title="Checkstyle">Checkstyle</a>
</li>
<li> <a href="aggregate-third-party-report.html" title="Third Parties (Aggregate mode)">Third Parties (Aggregate mode)</a>
</li>
<li> <a href="rat-report.html" title="Rat Report">Rat Report</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Other Resources <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="http://activitystrea.ms" title="ActivityStreams Homepage">ActivityStreams Homepage</a>
</li>
<li> <a href="http://activitystrea.ms/specs/" title="ActivityStreams Specifications">ActivityStreams Specifications</a>
</li>
<li> <a href="http://blogs.apache.org/streams/" title="Streams Blog">Streams Blog</a>
</li>
<li> <a href="http://wiki.apache.org/incubator/StreamsProposal" title="Streams Proposal Wiki Page">Streams Proposal Wiki Page</a>
</li>
<li> <a href="http://www.apache.org/" title="Apache Foundation Info">Apache Foundation Info</a>
</li>
<li> <a href="http://www.apache.org/foundation/sponsorship.html" title="Sponsorship">Sponsorship</a>
</li>
<li> <a href="http://www.apache.org/foundation/thanks.html" title="Thanks">Thanks</a>
</li>
</ul>
</li>
</ul>
<ul class="nav pull-right"><li>
<a href="https://twitter.com/ApacheStreams" class="twitter-follow-button" data-show-count="true" data-align="right" data-size="large" data-show-screen-name="true" data-lang="en">Follow ApacheStreams</a>
<script type="text/javascript">!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
</li></ul>
</div>
</div>
</div>
</div>
<div class="container">
<div id="banner">
<div class="pull-left">
<a href="http://streams.apache.org" id="bannerLeft">
<img src="http://streams.apache.org/images/streams_logo.jpg" alt="Apache Streams" width="150" height="100"/>
</a>
</div>
<div class="pull-right"> </div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li class="">
<a href="http://streams.apache.org" class="externalLink" title="Streams">
Streams</a>
<span class="divider">/</span>
</li>
<li class="active ">Website Management</li>
</ul>
</div>
<div id="bodyColumn" >
<div class="section">
<h2><a name="Website_Management"></a>Website Management</h2>
<p><a class="externalLink" href="http://streams.apache.org">http://streams.apache.org</a> is a set of interconnected websites generated from markdown by the maven site plugin. The front page, this page, and all pages aside from those organized under &#x2018;Examples&#x2019; reside in <a class="externalLink" href="http://github.com/apache/streams">http://github.com/apache/streams</a>. Those pages reside in <a class="externalLink" href="http://github.com/apache/streams-examples">http://github.com/apache/streams-examples</a></p>
<div class="section">
<h3><a name="Website_Content"></a>Website Content</h3>
<p>Pages, diagrams, and other hard-linkable resources are stored throughout the source tree.</p>
<div class="section">
<h4><a name="Markdown"></a>Markdown</h4>
<ul>
<li>src/site/markdown</li>
</ul>
<p>Most HTML pages are generated from markdown. The maven-site-plugin does this during the site build process.</p></div>
<div class="section">
<h4><a name="Schemas"></a>Schemas</h4>
<ul>
<li>src/main/jsonschema</li>
<li>src/main/xmlschema</li>
</ul>
<p>JSON and XML Schemas through-out the project are copied to the web page of their respective modules so they can be linked to in other projects.</p>
<p>This allows users to extend the canonical streams schemas incrementally and/or re-use specific fields as they see fit.</p></div>
<div class="section">
<h4><a name="Resources"></a>Resources</h4>
<ul>
<li>src/main/resources</li>
<li>src/test/resources</li>
</ul>
<p>Other resources including .conf and .properties files are copied to the web page of their respective modules so they can be linked to across projects and in external projects.</p>
<p>This allows users to import HOCON from modules outside their sphere of control and adapt to changes upstream.</p></div></div>
<div class="section">
<h3><a name="Website_Updates"></a>Website Updates</h3>
<p>The project website(s) are hosted by the Apache foundation and updated via SVN.</p>
<p>Currently pushing website changes is a manual process with several steps, performed by whomever is making the change.</p>
<p>This typically requires checking out the current website from SVN.</p>
<div class="source">
<div class="source"><pre class="prettyprint">svn co https://svn.apache.org/repos/asf/streams/site/trunk/content
cd content
</pre></div></div>
<p>NOTE:</p>
<p>Repositories should always be built and published in the following order:</p>
<ul>
<li>streams-project</li>
<li>streams-examples</li>
</ul>
<div class="section">
<h4><a name="Preparing_to_publishing_a_new_website_version"></a>Preparing to publishing a new website version</h4>
<p>The instructions below presume:</p>
<ul>
<li>you have a shell open in the SVN content directory</li>
<li>you know the artifactId and version of the repository you want to publish.</li>
</ul>
<p>If this is a brand new snapshot or release version, you first need to create a directory corresponding to the new version.</p>
<div class="source">
<div class="source"><pre class="prettyprint">mkdir site/${project.version}
svn add site/${project.version}
svn commit -m &quot;svn add site/${project.version}&quot;
</pre></div></div>
<p>The first time a specific site is being published for this version, you must create the directory where it will be published.</p>
<div class="source">
<div class="source"><pre class="prettyprint">mkdir site/${project.version}/${project.artifactId}
svn add site/${project.version}/${project.artifactId}
svn commit -m &quot;svn add site/${project.version}/${project.artifactId}&quot;
</pre></div></div>
<p>If you are published over an existing snapshot, you may need to first remove the existing version and recreate an empty directory.</p>
<div class="source">
<div class="source"><pre class="prettyprint">rm -rf site/${project.version}/${project.artifactId}
svn delete site/${project.version}/${project.artifactId}
svn commit -m &quot;svn delete site/${project.version}/${project.artifactId}&quot;
mkdir site/${project.version}/${project.artifactId}
svn add site/${project.version}/${project.artifactId}
svn commit -m &quot;svn add site/${project.version}/${project.artifactId}&quot;
</pre></div></div>
<p>In general however the scm plugin is smart enough to just add new resources and commit changes.</p>
<p>If you are publishing a release, it&#x2019;s appropriate to delete the site snapshots related to the prior releases.</p>
<p>For example when 0.5.2 is published, 0.5.1-SNAPSHOT should be deleted.</p>
<p>This policy of removing old snapshots keeps external projects from linking to snapshot artifacts indefinitely.</p>
<p>Release artifacts should be retained indefinitely.</p></div>
<div class="section">
<h4><a name="Generating_and_committing_a_new_website_version"></a>Generating and committing a new website version</h4>
<p>The instructions below presume:</p>
<ul>
<li>you have a shell open in the root of a project repository</li>
<li>you know the artifactId and version of the repository you want to publish.</li>
</ul>
<p>First, ensure that you have local credentials capable of publishing the site.</p>
<div class="source">
<div class="source"><pre class="prettyprint">&lt;server&gt;
&lt;id&gt;site.streams.{master|project|examples}&lt;/id&gt;
&lt;username&gt;{your apache ID}&lt;/username&gt;
&lt;privateKey&gt;{absolute path to your private key&lt;/privateKey&gt;
&lt;passphrase&gt;{your private key passphrase}&lt;/passphrase&gt;
&lt;filePermissions&gt;664&lt;/filePermissions&gt;
&lt;directoryPermissions&gt;775&lt;/directoryPermissions&gt;
&lt;configuration&gt;&lt;/configuration&gt;
&lt;/server&gt;
</pre></div></div>
<p>Next, generate SVG resources for all DOT diagrams in the source tree</p>
<div class="source">
<div class="source"><pre class="prettyprint">for dot in $(find . -name *.dot); do dot -Tsvg $dot -o $dot.svg; done
</pre></div></div>
<p>Then, generate the site that will be published</p>
<div class="source">
<div class="source"><pre class="prettyprint">mvn clean generate-sources package -Dmaven.test.skip.exec=true site:site site:stage
</pre></div></div>
<p>Double-check the logs and determine where exactly the staged site is located on your local drive.</p>
<p>At this point you can open target/staging/index.html (or wherever) and do a basic sanity check on the site you intend to publish.</p>
<p>Finally, publish the site.</p>
<div class="source">
<div class="source"><pre class="prettyprint">mvn scm-publish:publish-scm
</pre></div></div>
<p>You may need to provide -Dscmpublish.content=&lt;&gt; depending exactly where the staging site directory winds up.</p>
<p>Note the revision number checked in at the bottom of the maven logs.</p></div>
<div class="section">
<h4><a name="Updating_the_staging_site"></a>Updating the staging site</h4>
<p>Next step is to update the staging site and check it out.</p>
<p>Log into <a class="externalLink" href="https://cms.apache.org">https://cms.apache.org</a> with your apache credentials.</p>
<p>Use <a class="externalLink" href="https://cms.apache.org/streams">https://cms.apache.org/streams</a> to access the streams website.</p>
<p>Typically you can use Get streams Working Copy, although you might need to Force if you run into conflicts in SVN.</p>
<p>You&#x2019;ll probably need to &#x2018;Update this directory&#x2019; if you want to inspect the changes you committed above.</p>
<p>&#x2018;View Staging Builds&#x2019; should show a build around the time of the previous commit. This means the change has been staged.</p>
<p>You should now be able to access and review the published site(s) via the staging URL:</p>
<ul>
<li><a class="externalLink" href="http://streams.staging.apache.org/">http://streams.staging.apache.org/</a></li>
</ul>
<p>At this point use explicit versions to access and review the new documentation, i.e.</p>
<ul>
<li><a class="externalLink" href="http://streams.staging.apache.org/site/0.5.1/streams-project/index.html">http://streams.staging.apache.org/site/0.5.1/streams-project/index.html</a></li>
<li><a class="externalLink" href="http://streams.staging.apache.org/site/0.5.1/streams-examples/index.html">http://streams.staging.apache.org/site/0.5.1/streams-examples/index.html</a></li>
</ul></div>
<div class="section">
<h4><a name="Managing_version_pointers"></a>Managing version pointers</h4>
<p>When new versions of these sites are built for the first time, an additional set to alter Apache rules may be appropriate.</p>
<p>The convention we use exposes the latest specific site version(s) using redirects maintained in the .htaccess file of project website SVN.</p>
<p>These rules are located in the &#x2018;.htaccess&#x2019; file in the root of the SVN content directory and looks something like this:</p>
<div class="source">
<div class="source"><pre class="prettyprint">Options +FollowSymLinks
RewriteEngine on
RedirectMatch &quot;^/$&quot; &quot;/site/0.5.2-SNAPSHOT/streams-project&quot;
Redirect /site/latest /site/0.5.2-SNAPSHOT
Redirect /site/latest/streams-project /site/0.5.2-SNAPSHOT/streams-project
Redirect /site/latest/streams-examples /site/0.5.2-SNAPSHOT/streams-examples
</pre></div></div>
<p>Adjust the Redirect rules as appropriate for the project and version you are deploying. You can do this directly from the CMS.</p>
<p>Commit your changes, wait a few seconds, click Follow Staging Build, and you should see a new build with a &#x2018;Build Successful&#x2019; message.</p>
<p>You should now be able to use &#x2018;latest&#x2019; as an alias for the docs you are deploying, i.e.</p>
<ul>
<li><a class="externalLink" href="http://streams.staging.apache.org/site/latest/streams-project/index.html">http://streams.staging.apache.org/site/latest/streams-project/index.html</a></li>
<li><a class="externalLink" href="http://streams.staging.apache.org/site/latest/streams-examples/index.html">http://streams.staging.apache.org/site/latest/streams-examples/index.html</a></li>
</ul></div>
<div class="section">
<h4><a name="Promoting_a_new_website_version"></a>Promoting a new website version</h4>
<p>All that&#x2019;s left at this point is to promote from staging to production.</p>
<p>If a release is happening, this should happen just prior to the release announcement.</p>
<p>If you are just updating content associated with a snapshot, use good judgement to determine whether the list should have a chance to review and/or vote on the changes in staging prior to promotion.</p>
<div class="section">
<div class="section">
<h6><a name="Licensed_under_Apache_License_2.0_-_http:www.apache.orglicensesLICENSE-2.0"></a>Licensed under Apache License 2.0 - <a class="externalLink" href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a></h6></div></div></div></div></div>
</div>
</div>
<hr/>
<footer>
<div class="container">
<div class="row">
<p >Copyright &copy; 2018
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.
<li id="publishDate" class="pull-right">Last Published: 2018-04-02</li>
<li id="projectVersion" class="pull-right">
Version: 0.5.2-SNAPSHOT
</li>
</p>
</div>
<p id="poweredBy" class="pull-right">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
</a>
</p>
</div>
</footer>
</body>
</html>