YETUS-308 improve guidance on website maintenance. - give more pointers to middleman - explain location of website build output - details on publishing to the asf-site branch.
Signed-off-by: Allen Wittenauer <[email protected]> Signed-off-by: Chris Nauroth <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/yetus/repo Commit: http://git-wip-us.apache.org/repos/asf/yetus/commit/17cf9761 Tree: http://git-wip-us.apache.org/repos/asf/yetus/tree/17cf9761 Diff: http://git-wip-us.apache.org/repos/asf/yetus/diff/17cf9761 Branch: refs/heads/YETUS-344 Commit: 17cf9761002ea4769601933577800f57e8b513ca Parents: 4d5dd8d Author: Sean Busbey <[email protected]> Authored: Sun Feb 14 01:10:11 2016 -0600 Committer: Sean Busbey <[email protected]> Committed: Mon Feb 29 20:41:15 2016 -0600 ---------------------------------------------------------------------- asf-site-src/source/contribute/website.md | 37 ++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/yetus/blob/17cf9761/asf-site-src/source/contribute/website.md ---------------------------------------------------------------------- diff --git a/asf-site-src/source/contribute/website.md b/asf-site-src/source/contribute/website.md index 4130ae9..65c0167 100644 --- a/asf-site-src/source/contribute/website.md +++ b/asf-site-src/source/contribute/website.md @@ -19,7 +19,7 @@ # Maintaing the Yetus Website -We use middleman to generate the website content from markdown and other +We use [Middleman](https://middlemanapp.com/) to generate the website content from markdown and other dynamic templates. The following steps assume you have a working ruby 2.x environment setup: @@ -28,6 +28,9 @@ gem install bundler bundle install ``` +If you're interested in digging into how our site makes use of Middleman, or if you run into a problem, you should start +by reading [Middleman's excellent documentation](https://middlemanapp.com/basics/install/). + ## Make changes in asf-site-src/source Make any changes in the source directory: @@ -62,6 +65,12 @@ To generate the static wesbite for Apache Yetus run the following commands at th bundle exec middleman build ``` +This command will create a static website in the `publish` sub directory. You can load it in a web browser, e.g. assuming you are still in the asf-site-src directory on OS X: + +```bash +open publish/index.html +``` + ## Live Development Live development of the site enables automatic reload when changes are saved. To enable run the following command and then open a browser and navigate to @@ -72,5 +81,29 @@ bundle exec middleman ``` ## Publishing the Site -Commit the publish directory to the asf-site branch. +Commit the publish directory to the asf-site branch. Presuming we start in a directory that holds your normal Yetus check out: + +```bash +$ git clone --single-branch --branch asf-site https://git-wip-us.apache.org/repos/asf/yetus.git yetus-site +$ # Now build in the normal yetus check out +$ cd yetus +$ git fetch origin +$ git checkout master +$ git reset --hard origin/master +$ git clean -xdf +$ cd asf-site-src +$ bundle exec middleman build +$ rsync --quiet --checksum --inplace --recursive publish/ ../../yetus-site/ +$ cd ../../yetus-site +$ # check the set of differences +$ git add -p +$ # Verify any new files are also added +$ git status +$ # Try to reference the commit hash on master that this publication assures we include +$ git commit -m "git hash 6c6f6f6b696e6720746f6f20686172642c20796f" +$ # Finally publish +$ git push origin asf-site +``` +Publishing the website should be possible from the HEAD of the master branch under most circumstances. (See the [Guide for Release Managing](releases) for a notable time period where this won't be true.) +Documentation changes will be reviewed as they make their way into the master branch; updates to the `asf-site` branch are handled without further review.
