Moving our website generating system to docker from Vagrant. (#1)
[aurora-website.git] / README.md
index 88faa97e4cb56196859e1d5aee4343f93fb47d5a..ea2b4b75ee7c051b8558e4ad26dc3c2796ff5680 100644 (file)
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ on the Aurora IRC channel, #aurora on Freenode.net.
 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.
@@ -21,7 +21,7 @@ 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
+ * `content/`, where static-generated HTML files app live. Files in this directory are generated
    when the `rake2.0 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
@@ -31,16 +31,13 @@ The main directory includes a Rakefile, which will be used to run commands relat
 testing the website during development. More info below.
 
 ## Running and Developing the Website
-### Setting up Local Dev Environment
-The build environment for the website is managed by Vagrant.  To initialize the environment run:
 
-    vagrant up
+### Setting up Local Dev Environment using Docker
+From the root of the repository run the following:
 
-This will prepare the environment and generate the site.  Your local repository
-(the directory containing this README) will be mounted at `/vagrant` in the
-virtual machine.
+$ docker run -it -v $(pwd):/website -p 4567:4567 apache/aurora-website:dev
 
-**Note:** all rake commands must be run from `/vagrant`.
+Execute the remainder of the commands inside of this docker container.
 
 ### Generating the site
 To generate the site one only needs to run `rake2.0` after performing the setup
@@ -63,12 +60,6 @@ The majority of our documentation currently lives in git as markdown.  The `gene
 task automates the process of fetching the markdown, performing some translations, and
 storing it in a version-specific directory under `source/documentation`.
 
-First, prepare the vagrant environment and move into the `/vagrant` directory:
-
-    $ vagrant up
-    $ vagrant ssh
-    vagrant@vagrant-ubuntu-trusty-64:~$ cd /vagrant
-
 You will use the `generate_docs` rake task to fetch the docs you wish to place on the website.
 This task takes two arguments - `title` and `git_tag`.  The title is the name to give this branch
 of documentation.
@@ -89,8 +80,10 @@ misleading documentation for unreleased featuresl
 After completing an official Aurora release, you should add the new version of documentation and
 advertise the release on the website.
 
+$RELEASE in this case is the number version of the release (i.e. 0.22.0).
+
 First, add the new release to the top of `data/downloads.yml`.
+
     # Add documentation for the new release
     rake2.0 generate_docs[$RELEASE,$RELEASE]
 
@@ -100,30 +93,42 @@ First, add the new release to the top of `data/downloads.yml`.
     # Render the docs.
     rake2.0
 
-### Development 
-To live edit the site run `rake2.0 dev` and then open a browser window to 
-`http://192.168.33.10:4567`. Any change you make to the sources dir will 
-be shown on the local dev site immediately. Errors will be shown in the 
+### Development
+To live edit the site run `rake2.0 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 `rake2.0 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.
+Make a PR to our website repository through Github.
 
 ## 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.
+The website uses Apache Infra tooling to sync this Git repository with the live site.
+
+The content folder contains the websites content and when changes are committed to the asf-staging
+or asf-site branches, changes will be automatically deployed.
+
+Before committing ensure that changes from source/ have been properly built in the `content/`
+directory.
+
+`$ git add content source`
+`$ git commit -m "Message describing the website changes you've made."`
+
+Updates to the current website should first be submitted as a Pull Request to the asf-staging branch.
+
+Once the PR has been merged in the asf-staging branch, a live preview will be available at:
+https://aurora.staged.apache.org/
 
-Before commiting, ensure that changes from source/ have been properly built in the `publish/`
-directory. Changes will be published to the website by running:
+If the site looks good and functions correctly, a PR should be made to the asf-site branch
+from the asf-staging branch, squashing all commits into a single commit detailing
+the change (usually a release).
 
-    svn commit -m "Message describing the website changes you've made."
+Note: there is sometimes a slight delay between merging PRs and
+changes appearing online.
 
 ### Apache License
 Except as otherwise noted this software is licensed under the