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)
