From 3905d799dcf7488e16df386ac36bc302f0f5116a Mon Sep 17 00:00:00 2001
From: Paul Tan <pyokagan@gmail.com>
Date: Sat, 9 Dec 2017 21:15:55 +0800
Subject: [PATCH] Setup CircleCI for previewing documentation changes

When submitting a PR with changes to the documentation, it would be
useful to give the reviewer a way to easily see the results of the
changes in the built HTML documentation so that they do not need to
build the documentation themselves. Presently, this is usually done by:

    (1) adding screenshots highlighting the changes to the reviewer, or
    (2) temporarily hosting the built documentation somewhere.

For (1), screenshots may not paint a complete picture of the impact of
the changes (e.g. how the changes would fit into the "visual feel" of
the whole website), and so a reviewer might need the *whole* website in
order to give a good assessment of the changes. On the other hand, (2)
requires quite a bit of effort on the PR author's part, and there is
always the concern that the hosted website may not be kept updated with
the actual changes in the PR.

So, we need a solution that builds the PR just like AppVeyor and
Travis CI does, but stores the built documentation and hosts it
somewhere for reviewers to look at. Something like AppVeyor's build
artifacts feature.

However, while AppVeyor does allow us to store build artifacts, it does
not serve the hosted artifacts with the correct MIME type. Visitors to
those files will simply be prompted by their web browser to download the
file.

Travis CI does not support storing build artifacts, requiring them to be
uploaded to another service such as Amazon S3.

As such, we will need to find another way.

CircleCI[1] is a popular CI service that does provide what we want.
Our builds can upload build artifacts, and CircleCI will serve them with
the correct MIME type, allowing reviewers to easily browse the built
documentation files via their web browser.

So, let's add a CircleCI config file to our repo telling CircleCI how to
build our documentation, and store it as a build artifact. Reviewers can
then view the built documentation by navigating to the build job page,
clicking on the "Artifacts" tab and then clicking on the file they want
to view.

Why not run tests as well? Well, there is a slight problem: CircleCI's
free plan only gives us 1500 minutes of build time, and our full build +
tests presently take around 3 minutes to run (and might increase in the
future as more system tests are added). So, considering the fact that we
will setup CircleCI to run on all our PRs, and some developers might
prefer to use our CIs rather than running tests locally on their own
computers, this 1500 minutes limit might be problematic for us.

As such, for now, we'll just configure CircleCI to only build our
documentation, so that builds complete much faster (around 30s). We have
Travis CI to run our tests, anyway.

[1] https://circleci.com/
---
 .circleci/config.yml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 .circleci/config.yml

diff --git a/.circleci/config.yml b/.circleci/config.yml
new file mode 100644
index 000000000000..a97fcbfb8abb
--- /dev/null
+++ b/.circleci/config.yml
@@ -0,0 +1,36 @@
+# CircleCI configuration file
+# For more details see https://circleci.com/docs/2.0/
+
+version: 2
+jobs:
+  build:
+    docker:
+      - image: openjdk:8-jdk
+    working_directory: ~/project
+    steps:
+      - checkout
+      - run:
+          name: Setup environment variables
+          command: echo 'export TERM=dumb' >>"$BASH_ENV"
+      - restore_cache:
+          keys:
+            # Increment the version number e.g. v2-gradle-cache-...
+            # to force the caches to be "invalidated".
+            - v1-gradle-cache-{{ checksum "build.gradle" }}
+            - v1-gradle-cache-
+      - run:
+          name: Build documentation
+          command: ./gradlew clean asciidoctor
+      - store_artifacts:
+          path: ~/project/build/docs/html5
+          destination: docs
+      - run:
+          name: Cleanup for save_cache
+          command: >-
+            rm -f $HOME/.gradle/caches/modules-2/modules-2.lock
+            rm -fr $HOME/.gradle/caches/*/plugin-resolution/
+      - save_cache:
+          key: v1-gradle-cache-{{ checksum "build.gradle" }}
+          paths:
+            - ~/.gradle/caches
+            - ~/.gradle/wrapper