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 <aw@apache.org>
Signed-off-by: Chris Nauroth <cnauroth@apache.org>
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 @@
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 @@
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 @@
```
## 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.
