fix typos on faq and a broken link
Project: http://git-wip-us.apache.org/repos/asf/incubator-streams-master/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-streams-master/commit/2cd53890 Tree: http://git-wip-us.apache.org/repos/asf/incubator-streams-master/tree/2cd53890 Diff: http://git-wip-us.apache.org/repos/asf/incubator-streams-master/diff/2cd53890 Branch: refs/heads/master Commit: 2cd53890bf01e52c632ecaa8418dbcdfc17c1b68 Parents: 02e9743 Author: Steve Blackmon @steveblackmon <[email protected]> Authored: Sat Apr 30 15:06:10 2016 -0500 Committer: Steve Blackmon @steveblackmon <[email protected]> Committed: Sat Apr 30 15:06:10 2016 -0500 ---------------------------------------------------------------------- src/site/markdown/faq.md | 19 +++++---- src/site/markdown/website.md | 86 ++++++++++++++++++++++++--------------- src/site/site.xml | 3 +- src/site/site_en.xml | 4 +- 4 files changed, 68 insertions(+), 44 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-streams-master/blob/2cd53890/src/site/markdown/faq.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md index 9c202ad..6d41649 100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@ -55,15 +55,15 @@ If you are sure you can write code that is some combination of faster, more read But you are probably under-estimating how difficult it will be to optimize across all of these considerations, stay current with upgrades to underlying libraries, and fix whatever bugs are discovered. -Or maybe you are capable of doing it all flawlessly, but your time is just more valuable focused on your product rather than on plumbing +Or maybe you are capable of doing it all flawlessly, but your time is just more valuable focused on your product rather than on plumbing. -By joining forces with others who care about clean running water, everyone can run better, faster, stronger code: assembled with more diverse expertise for and tested in use cases beyond your own. +By joining forces with others who care about clean running water, everyone can run better, faster, stronger code assembled with more diverse expertise, tested and tuned under more use cases. ### How is streams different than "*processing framework*"? -You don't have to look hard to find great data processing frameworks for batch or for real-time. Pig, Hive, Storm, Spark, Samza, Flink, and Google Cloud Dataflow (soon-to-be Apache Beam) are all great. Apex and NiFi are interesting newer options. And this list only Apache Foundation JVM projects! +You don't have to look hard to find great data processing frameworks for batch or for real-time. Pig, Hive, Storm, Spark, Samza, Flink, and Google Cloud Dataflow (soon-to-be Apache Beam) are all great. Apex and NiFi are interesting newer options. This list only includes Apache Foundation JVM projects! -At the core these platforms help you specify inputs, outputs, and a directed graph of computation and then run your code at scale. +At the core these platforms help you connect inputs and outputs to a directed graph of computation, and run your code at scale. Streams use this computational model as well, but is more focused on intelligently and correctly modeling the data that will flow through the stream than on stream execution. In this sense Streams is an alternative to avro or protocol buffers - one which prioritizes flexibility, expressivity, interoperability, and tooling ahead of speed or compute efficiency. @@ -122,10 +122,15 @@ Where quality java libraries exist, their most useful parts may be included with ### Where do I start? -Work your way through the list of 'Tutorial' items above to get up and running with streams. +Work your way through the 'Tutorial' menu to get up and running with streams. -Then browse the 'Getting Started' items to learn more about how streams works and why. +Then browse the 'Other Resources' menu to learn more about how streams works and why. ### How can I help? -Please join our mailing list, then ask questions and suggest features. Contribute to the documentation in one of the streams repositories. Consider writing a new provider using an existing provider as a template. Consider adding a feature (and / or tests) to an existing module you intend to use. Consider building and contributing a new example. +* Join our mailing list. +* Ask questions and suggest features. +* Contribute to the documentation in one of the streams repositories. +* Write a new provider using an existing provider as a template. +* Add new features (and / or tests) to an existing module you intend to use. +* Build and contributing a new example. http://git-wip-us.apache.org/repos/asf/incubator-streams-master/blob/2cd53890/src/site/markdown/website.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/website.md b/src/site/markdown/website.md index 06f71a1..4b8c3e5 100644 --- a/src/site/markdown/website.md +++ b/src/site/markdown/website.md @@ -2,7 +2,9 @@ http://streams.incubator.apache.org is a set of interconnected websites generated by the maven site plugin. The front page, this page, and most pages linked in the -top nav of the site are part of incubator-streams-master. +top nav of the site are part of incubator-streams-master. incubator-streams and +incubator-streams-examples also contain documentation of specific modules and examples that +are part of the project webpage. ### Website Content @@ -38,11 +40,11 @@ This allows users to import HOCON from modules outside their sphere of control a The project website(s) are hosted by the Apache foundation and updated via SVN. -Currently pushing website changes is a manual process performed by whomever is making the change. +Currently pushing website changes is a manual process with several steps, performed by whomever is making the change. This typically requires checking out the current website from SVN. - svn co https://svn.apache.org/repos/infra/websites/production/streams/content + svn co https://svn.apache.org/repos/asf/incubator/streams/site/trunk/content cd content NOTE: @@ -83,7 +85,15 @@ If you are published over an existing snapshot, you must first remove the existi The folder must exist and be empty for the publish steps to succeed. -#### Generating and publishing a new website version +If you are publishing a release, it's appropriate to delete the site snapshots related to the prior releases. + +For example when 0.3-incubating is published, 0.2-incubating-SNAPSHOT should be deleted. + +This policy of removing old snapshots keeps external projects from linking to snapshot artifacts indefinitely. + +Release artifacts should be retained indefinitely. + +#### Generating and committing a new website version The instructions below presume: @@ -114,57 +124,67 @@ At this point you can open target/staging/index.html and do a sanity check on th Finally, publish the site. - mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:svn:https://svn.apache.org/repos/infra/websites/production/streams/content/site/${project.version}/${project.artifactId} + mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:svn:https://svn.apache.org/repos/asf/incubator/streams/site/trunk/content/site/${project.version}/${project.artifactId} You may need to provide -Dscmpublish.content= depending where the staging site directory winds up under target/ Note the revision number checked in at the bottom of the maven logs. -You should now be able to access the published site(s) via an absolute URL such as http://streams.incubator.apache.org/site/${project.version}/${project.artifactId} - -For example, website documentation from a recent release: +#### Updating the staging site -* http://streams.incubator.apache.org/site/0.2-incubating/streams-project/index.html +Next step is to update the staging site and check it out. -Some recent snapshots: +Log into https://cms.apache.org with your apache credentials. -* http://streams.incubator.apache.org/site/0.3-incubating-SNAPSHOT/streams-master/index.html -* http://streams.incubator.apache.org/site/0.3-incubating-SNAPSHOT/streams-project/index.html -* http://streams.incubator.apache.org/site/0.2-incubating-SNAPSHOT/streams-examples/index.html +Use https://cms.apache.org/streams to access the streams website. -#### Promoting a new website version +Typically you can use Get streams Working Copy, although you might need to Force if you run into conflicts in SVN. -New release or snapshots are immediately published, but visitors to the website won't arrive there from standard links and navigation -until it has been fully promoted. - -The instructions below presume: +You'll probably need to 'Update this directory' if you want to inspect the changes you committed above. -* you have a shell open in the SVN content directory -* you know the artifactId and version of the repository you want to publish. +'View Staging Builds' should show a build around the time of the previous commit. This means the change has been staged. + +You should now be able to access and review the published site(s) via the staging URL: -The convention in place exposes the latest specific site version(s) using redirects maintained in the .htaccess file of project website SVN. +* http://streams.staging.apache.org/ + +At this point use explicit versions to access and review the new documentation, i.e. -This file can be edited from https://cms.apache.org/streams/ +* http://streams.staging.apache.org/site/0.3-incubating-SNAPSHOT/streams-master/index.html +* http://streams.staging.apache.org/site/0.3-incubating-SNAPSHOT/streams-project/index.html +* http://streams.staging.apache.org/site/0.3-incubating-SNAPSHOT/streams-examples/index.html -First, click 'Get streams Working Copy' +#### Managing version pointers -Next, open .htaccess +When new versions of these sites are built for the first time, an additional set to alter Apache rules may be appropriate. -If you are promoting sites from all streams repositories simultaneously, the file should end with: +The convention we use exposes the latest specific site version(s) using redirects maintained in the .htaccess file of project website SVN. - Redirect /site/latest/ /site/${project.version} - -If you want to expose sites hosted under different versions across streams repositories: +These rules are located in the '.htaccess' file in the root of the SVN content directory and looks something like this: + Options +FollowSymLinks + RewriteEngine on + RedirectMatch "^/$" "/site/0.3-incubating-SNAPSHOT/streams-master" + Redirect /site/latest /site/0.3-incubating-SNAPSHOT Redirect /site/latest/streams-master /site/0.3-incubating-SNAPSHOT/streams-master - Redirect /site/latest/streams-project /site/0.2-incubating/streams-project + Redirect /site/latest/streams-project /site/0.3-incubating-SNAPSHOT/streams-project Redirect /site/latest/streams-examples /site/0.3-incubating-SNAPSHOT/streams-examples -Commit your changes. +Adjust the Redirect rules as appropriate for the project and version you are deploying. You can do this directly from the CMS. -Wait a few seconds and click Follow Staging Build. +Commit your changes, wait a few seconds, click Follow Staging Build, and you should see a new build with a 'Build Successful' message. + +You should now be able to use 'latest' as an alias for the docs you are deploying, i.e. + +* http://streams.staging.apache.org/site/latest/streams-master/index.html +* http://streams.staging.apache.org/site/latest/streams-project/index.html +* http://streams.staging.apache.org/site/latest/streams-examples/index.html + +#### Promoting a new website version -You should see a new build with a 'Build Successful' message. +All that's left at this point is to promote from staging to production. -Open a new tab and visit http://streams.staging.apache.org for one last check before go-live. +If a release is happening, this should happen just prior to the release announcement. +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. http://git-wip-us.apache.org/repos/asf/incubator-streams-master/blob/2cd53890/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index da3c126..3e63fb7 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -86,12 +86,11 @@ <item name="Set up a local docker environment" href="tutorial/docker.html" /> <item name="Run a local database to store activity documents" href="tutorial/database.html" /> <item name="Run twitter-history-elasticsearch" href="http://streams.incubator.apache.org/site/latest/streams-examples/streams-examples-local/twitter-history-elasticsearch/index.html"; /> - <item name="Run twitter-history-elasticsearch" href="http://streams.incubator.apache.org/site/latest/streams-examples/streams-examples-local/twitter-history-elasticsearch/index.html"; /> </menu> <menu name="Learn More"> <item name="Browse streams providers, processors, and persisters" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-contrib/index.html"; /> <item name="View the official Apache Streams jsonschema files" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-pojo/index.html"; /> - <item name="View java POJOs generated from the official Apache Streams jsonschema files" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-contrib/streams-pojo/apidocs/index.html"; /> + <item name="View java POJOs generated from the official Apache Streams jsonschema files" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-pojo/apidocs/org/apache/streams/pojo/json/package-summary.html"; /> <item name="Check out some additional examples" href="http://streams.incubator.apache.org/site/latest/streams-examples/index.html"; /> </menu> <menu name="Other Resources"> http://git-wip-us.apache.org/repos/asf/incubator-streams-master/blob/2cd53890/src/site/site_en.xml ---------------------------------------------------------------------- diff --git a/src/site/site_en.xml b/src/site/site_en.xml index cce4000..5e612eb 100644 --- a/src/site/site_en.xml +++ b/src/site/site_en.xml @@ -77,7 +77,7 @@ <item name="Website Management" href="website.html" /> </menu> <menu name="Projects" inherit="top"> - <item name="streams-master" /> + <item name="streams-master" href="http://streams.incubator.apache.org/site/latest/streams-master"; /> <item name="streams-project" href="http://streams.incubator.apache.org/site/latest/streams-project"; /> <item name="streams-examples" href="http://streams.incubator.apache.org/site/latest/streams-examples/"; /> </menu> @@ -91,7 +91,7 @@ <menu name="Learn More"> <item name="Browse streams providers, processors, and persisters" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-contrib/index.html"; /> <item name="View the official Apache Streams jsonschema files" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-pojo/index.html"; /> - <item name="View java POJOs generated from the official Apache Streams jsonschema files" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-contrib/streams-pojo/apidocs/index.html"; /> + <item name="View java POJOs generated from the official Apache Streams jsonschema files" href="http://streams.incubator.apache.org/site/latest/streams-project/streams-pojo/apidocs/org/apache/streams/pojo/json/package-summary.html"; /> <item name="Check out some additional examples" href="http://streams.incubator.apache.org/site/latest/streams-examples/index.html"; /> </menu> <menu name="Other Resources">
