This is an automated email from the ASF dual-hosted git repository. szetszwo pushed a commit to branch asf-site-source in repository https://gitbox.apache.org/repos/asf/ratis-hadoop-projects.git
commit d80d20dbf7b8942ea95175b46a2b30929a2f3994 Author: Josh Elser <[email protected]> AuthorDate: Tue Jun 4 14:12:52 2019 -0400 RATIS-582. Update website instructions Also fixes build.sh to properly download from mirrors and validate the bits downloaded from the untrusted location. Allow build.sh to build to a user-provided directory. --- README.md | 43 +++++++++++++++++++++++++++++++++++++++---- build.sh | 48 +++++++++++++++++++++++++++++++++++++++++------- rat-excludes.txt | 17 +++++++++++++++++ 3 files changed, 97 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 308d009..e5f72cb 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,53 @@ 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 manually edit content in 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 (presently) no automation to automatically keep these branches in sync, but a general guide is to do the following. +These steps use two checkouts of the Git repo, one for `asf-site` and another for `asf-site-source`. Beware that these steps +are destructive to any local modifications: + +First time only! +```bash +$ git clone https://github.com/apache/incubator-ratis ratis-site.git +$ cp -r ratis-site.git ratis-site-source.git +$ pushd ratis-site.git && git checkout -t origin/asf-site && popd +$ pushd ratis-site-source.git && git checkout -t origin/asf-site-source && popd +``` + +To modify the website: +```bash +$ pushd ratis-site.git && git pull && popd +$ pushd ratis-site-source.git && git pull +$ # hack hack hack +$ ./build.sh ../ratis-site.git +``` diff --git a/build.sh b/build.sh index f657d86..b238e9c 100755 --- a/build.sh +++ b/build.sh @@ -17,17 +17,51 @@ 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 -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 +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 + +if [[ $# -ne 1 ]]; then + echo "Usage: ./build.sh <website_output>" + exit 3 +fi + +BUILD_OUTPUT_DIR="$1" 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 ${BUILD_OUTPUT_DIR}" +$HUGO_EXEC -d ${BUILD_OUTPUT_DIR} diff --git a/rat-excludes.txt b/rat-excludes.txt new file mode 100644 index 0000000..002ea2f --- /dev/null +++ b/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
