svn commit: r1671111 - /aurora/site/README.md

[dl...@apache.org]

Author: dlester
Date: Fri Apr  3 17:52:41 2015
New Revision: 1671111

URL: http://svn.apache.org/r1671111
Log:
Update Aurora website README to improve instructions for updating website.

Modified:
    aurora/site/README.md

Modified: aurora/site/README.md
URL: http://svn.apache.org/viewvc/aurora/site/README.md?rev=1671111&r1=1671110&r2=1671111&view=diff
==============================================================================
--- aurora/site/README.md (original)
+++ aurora/site/README.md Fri Apr  3 17:52:41 2015
@@ -1,15 +1,34 @@
 # Apache Aurora Website
-This will generate the Apache Aurora available at http://aurora.apache.org. The content
-within the publish folder will be the actual deployed site.
+This codebase generates the Apache Aurora available at [http://aurora.apache.org](http://aurora.apache.org).
 
+Community contributions and patches are welcomed to help keep the Aurora site up-to-date; please see the section below on contributing website changes or feel free to ask questions on the Aurora IRC channel, #aurora on Freenode.net.
 
+## Website Basics
+### Middleman CMS
+The Aurora website is powered by [Middleman](http://middlemanapp.com/), a static website generator written in ruby. If you'd like to learn more about Middleman and how it works, their official websites have helpful documentation.
+ 
 ## Setup
+For most website-related changes, knowledge of Middleman or Ruby are unnecessary; Middleman is used to convert markdown files to HTML and handle dynamic templates.
+
+### Directory Structure
+The website has three sub-directories:
+
+ * `source/`, which includes site templates and markdown files. This is the directory you will revise documents in 99% of the time.
+ * `publish/`, where static-generated HTML files app live. Files in this directory are generated when the `rake build` command is run, and these files are served via HTTP on the Aurora website.
+ * `tmp/`, a directory used when cloning the remote project repository before processing documentation and other files.
+
+The main directory includes a Rakefile, which will be used to run commands related to building and testing the website during development. More info below.
+
+## Running and Developing the Website
+### Setting up Local Dev Environment
+In order to build the Apache Aurora website locally, you must be running Ruby 2.0+.
+
+Once running a proper ruby version, install required Ruby gems by running the following:
 
 		gem install bundler
 		bundle install
-		
 
-## Generating the site
+### Generating the site
 To generate the site one only needs to run `rake` after performing the setup
 tasks mentioned above. This will download the latest Apache Aurora documentation
 contained in the `docs` folder, integrate them into the site, and generate all
@@ -17,28 +36,31 @@ other files within the source folder.
 
 		rake
 
+### Other available tasks
+
+		rake build				# Build the website from source
+		rake clean				# Remove any temporary products
+		rake clobber			# Remove any generated file
+		rake dev				# Run the site in development mode
+		rake update_docs  		# Update the latest docs from the Apache Aurora codebase
 
-## Development 
+### Development 
 To live edit the site run `rake dev` and then open a browser window to 
 http://localhost:4567/ . Any change you make to the sources dir will 
 be shown on the local dev site immediately. Errors will be shown in the 
 console you launched `rake dev` within.
 
+## Contributing Website Changes
+Have you made local changes that you would like to contribute to the website? While we use Apache [ReviewBoard](http://reviews.apache.org) for changes to the primary Aurora codebase, website changes are currently reviewed by attaching diffs to Apache JIRA tickets.
 
-## Other available tasks
-
-		rake build        # Build the website from source
-		rake clean        # Remove any temporary products
-		rake clobber      # Remove any generated file
-		rake dev          # Run the site in development mode
-		rake update_docs  # Update the latest docs from the Apache Aurora codebase
+## Publishing Changes to the Website
+All project committers have access to commit to the Aurora website; we encourage those without commit access to contribute changes by following the steps above.
 
+The website uses svnpubsub to sync changes in this SVN repository with the live site. The publish folder contains the websites content and when committed to the svn repository it will be automatically deployed. Note: there is sometimes a slight delay between committing to SVN and appearing online.
 
-## Publishing the Site
-The website uses svnpubsub. The publish folder contains the websites content
-and when committed to the svn repository it will be automatically deployed to 
-the live site. 
+Before commiting, ensure that changes from source/ have been properly built in the publish/ directory. Changes will be published to the website by running:
 
+		svn commit -m "Message describing the website changes you've made."
 
 ### Apache License
 Except as otherwise noted this software is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)