[5/6] git commit: Add README.md on building and publishing

[ri...@apache.org]

Add README.md on building and publishing


Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn-site/commit/81ad1051
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn-site/tree/81ad1051
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn-site/diff/81ad1051

Branch: refs/heads/master
Commit: 81ad105121c1e0fcde5831e544a3120e454da74e
Parents: 7afae86
Author: Richard Downer <ri...@apache.org>
Authored: Thu Jul 10 11:58:36 2014 +0000
Committer: Richard Downer <ri...@apache.org>
Committed: Thu Jul 10 11:58:36 2014 +0000

----------------------------------------------------------------------
 README.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn-site/blob/81ad1051/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..31512ec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+Brooklyn Website source
+=======================
+
+Contributor worflow
+-------------------
+
+The contributor workflow is identical to that used by the main project, with
+the exception of the different repository - `incubator-brooklyn-site` instead
+of `incubator-brooklyn`. Therefore you should familiarise yourself with the
+standard workflow for Apache Brooklyn:
+
+* [Guide for contributors][CONTRIB]
+* [Guide for committers][COMMIT]
+
+[CONTRIB]: https://brooklyn.incubator.apache.org/community/how-to-contribute.html
+[COMMIT]: https://brooklyn.incubator.apache.org/community/committers.html
+
+
+Workstation setup
+-----------------
+
+First, clone the `incubator-brooklyn-site` repository and set up the remotes as
+described in [Guide for committers][COMMIT].
+
+Install [RVM](http://rvm.io/); this manages Ruby installations and sets of Ruby
+gems.
+
+    \curl -sSL https://get.rvm.io | bash -s stable
+
+At this point, close your shell session and start a new one, to get the new
+environment that RVM has configured. Now change directory to the location where
+you checked out your repository; RVM should detect its configuration inside
+`Gemfile` and try to configure itself. Most likely it will report that the
+required version of Ruby is not installed; it will show the command that you
+need to run to install the correct version. Follow the instructions.
+
+Once the correct version of Ruby is installed, change to your home directory
+(`cd ~`) and then change back to the repository again (`cd -`). This will cause
+RVM to re-load configuration from `Gemfile` with the correct version of Ruby.
+
+If you are running Ubuntu, there is a further dependency that is required:
+
+    sudo apt-get install libxslt-dev libxml2-dev
+
+Finally, run this command to install all the required Gems in the correct
+versions:
+
+    bundle install
+
+
+Building and previewing the website
+-----------------------------------
+
+Run this script:
+
+    ./_scripts/build-preview
+
+This will run Jekyll using a base URL of type `file://` for the repository
+directory. This means that it is possible to browse the generated files,
+located in the `_site` directory, using a web browser pointed at your
+filesystem. Unfortunately it does mean that moving the files, or attempting to
+point a web server host at them, will not work.
+
+
+Building and publishing the website
+-----------------------------------
+
+Run this script:
+
+    ./_scripts/build-for-publication
+
+This will run Jekyll with the correct base URL for the live website and place
+the output in the `_site` directory.
+
+The Apache website publication process is based around the Subversion repository; the generated HTML files must be checked in to Subversion, whereupon an automated process will publish the files to the live website.
+
+Starting in a suitable directory, check out the website directory from the repository:
+
+    svn co https://svn.apache.org/repos/asf/incubator/brooklyn/site incubator-brooklyn-site-public
+    cd incubator-brooklyn-site-public
+
+Synchronise the generated site into the Subversion working copy - please amend this command to include the correct paths for your setup:
+
+    rsync -rv --delete --exclude .svn --exclude v ~/incubator-brooklyn-site/_site/ ~/incubator-brooklyn-site-public
+
+Review the changes using the usual `svn` commands - e.g., `status`, `diff`, `add`, `rm`, etc.
+
+Once you are ready to publish, commit the changes to Subversion:
+
+    svn ci -m 'Update Brooklyn (incubating) website'
+
+The changes will become live within a few minutes.