RATIS-582 Update website instructions

README.md

@@ -16,18 +16,47 @@
 
 This is the source code of the website of Apache Ratis.
 
+## Hugo Installation
+
 To render it you need hugo static site generator (https://gohugo.io/getting-started/installing) which is available for the most popular platforms as a single binary.
 
-To render the final website use the following command:
+On OSX, this can be installed via HomeBrew: `brew install hugo`. For other operating system, please refer to the
+aforementioned Hugo documentation for installation steps.
+
+## Building
+
+To render the final website, use the provided `build.sh` script. This script will generate the website in the directory
+`public/` and also perform a license check on the source files (prior to commit).
 
 ```
-hugo -d /destination/dir
+hugo
 ```
 
-To develop the site use
+To iteratively develop the website, you can use the `serve` command to start a local webserver with your content changes
+rendered in realtime:
 
 ```
 hugo serve
 ```
 
-which starts an internal server where you can always check the final rendered version.
+## Publishing website changes
+
+Committers must ensure that the state of the `asf-site-source` and `asf-site` branches are in sync at all times.
+Committers must never make changes directly to the `asf-site` branch.
+
+Content pushed to the `asf-site` branch is automatically published to the public website:
+https://ratis.incubator.apache.org
+
+There is no automation to automatically keep these branches in sync, but a general guide is to do the following. Beware
+that these steps are destructive!
+
+```bash
+$ git checkout asf-site-source && //hack hack hack
+$ ./build.sh
+$ mv public ../
+$ git checkout asf-site
+$ rm -i ./*
+* cp ../public/*
+$ rm -i -r categories post tags
+$ cp -r ../public/categories ../public/post ../public/tags .
+```

build.sh

@@ -17,17 +17,45 @@
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 set -e
 mkdir -p build
-if [ ! -d "$DIR/build/apache-rat-0.12" ]; then
-   wget http://xenia.sote.hu/ftp/mirrors/www.apache.org/creadur/apache-rat-0.12/apache-rat-0.12-bin.tar.gz -O $DIR/build/apache-rat.tar.gz
-	cd $DIR/build
-	tar zvxf apache-rat.tar.gz
-	cd -
+rat_version="0.13"
+filename="apache-rat-${rat_version}-bin.tar.gz"
+artifact="creadur/apache-rat-${rat_version}/${filename}"
+if [ ! -f "$DIR/build/${filename}" ]; then
+  echo "RAT installation missing, download to build/"
+  curl -L --fail -o "${DIR}/build/${filename}" "https://www.apache.org/dyn/closer.lua?filename=${artifact}&action=download"
+  curl -L --fail -o "${DIR}/build/${filename}.sha512" "https://dist.apache.org/repos/dist/release/${artifact}.sha512"
+fi
+
+if [ ! -d "$DIR/build/apache-rat-${rat_version}" ]; then
+  echo "Unpacked RAT installation missing, validating download RAT release using checksum"
+  pushd ${DIR}/build >/dev/null
+  gpg --print-md SHA512 ${filename} | diff ${filename}.sha512 -
+  if [[ $? -ne 0 ]]; then
+    echo "Failed to validate checksum of ${filename}"
+    # Cleanup before exiting to avoid this stuff hanging around that is untrusted
+    rm ${DIR}/build/${filename}
+    rm ${DIR}/build/${filename}.sha512
+    exit 2
+  fi
+  popd >/dev/null
+  # Only now is it safe to extract this
+  tar zxf build/${filename} -C build/
+fi
+
+echo "Running RAT license check"
+output=$(java -jar $DIR/build/apache-rat-${rat_version}/apache-rat-${rat_version}.jar -d $DIR -E rat-excludes.txt)
+if [[ ! $(echo "$output" | grep '0 Unknown Licenses') ]]; then
+  echo 'RAT check appears to have failed, inspect its output:'
+  echo "$output"
+  exit 1
+else
+  echo "RAT check appears to have passed"
 fi
-java -jar $DIR/build/apache-rat-0.12/apache-rat-0.12.jar $DIR -e public -e apache-rat-0.12 -e .git -e .gitignore
 
 HUGO_EXEC=$(which hugo)
 if [ "$?" -ne 0 ]; then
       echo "Please install hugo and put it to the path"
 		exit 1
 fi
-$HUGO_EXEC
+echo -e "\nBuilding website to public/"
+$HUGO_EXEC -d public

rat-excludes.txt

@@ -0,0 +1,17 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License. See accompanying LICENSE file.
+#
+.git
+.gitignore
+build
+public