From 735c7c984109a90c1b87b65969c91188cf648efe Mon Sep 17 00:00:00 2001
From: Dan Albert <dan@solana.com>
Date: Mon, 22 Jul 2019 17:45:00 -0600
Subject: [PATCH] Add manual publish for book and create book-beta (#5112)

---
 RELEASE.md         | 33 ++++++++++++++++++++------
 ci/publish-book.sh | 58 +++++++++++++++++++++++++++++++++-------------
 2 files changed, 68 insertions(+), 23 deletions(-)

diff --git a/RELEASE.md b/RELEASE.md
index acc28011b..fbb5df992 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -61,7 +61,7 @@ There are three release channels that map to branches as follows:
 
 ## Release Steps
 
-### Advance the Channels
+### Creating a new branch from master
 
 #### Create the new branch
 1. Pick your branch point for release on master.
@@ -84,6 +84,12 @@ There are three release channels that map to branches as follows:
 At this point, `ci/channel-info.sh` should show your freshly cut release branch as
 "BETA_CHANNEL" and the previous release branch as "STABLE_CHANNEL".
 
+### Update documentation
+
+Document the new recommended version by updating
+```export SOLANA_RELEASE=[new scheduled TESTNET_TAG value]```
+in book/src/testnet-participation.md on the release (beta) branch.
+
 ### Make the Release
 
 We use [github's Releases UI](https://github.com/solana-labs/solana/releases) for tagging a release.
@@ -106,6 +112,25 @@ We use [github's Releases UI](https://github.com/solana-labs/solana/releases) fo
 1. Push your Cargo.toml change and the autogenerated Cargo.lock changes to the
    release branch.
 
+### Publish updated Book
+We maintain three copies of the "book" as official documentation:
+
+1) "Book" is the documentation for the latest official release.  This should get manually updated whenever a new release is made.  It is published here:
+https://solana-labs.github.io/book/
+
+2) "Book-edge" tracks the tip of the master branch and updates automatically.
+https://solana-labs.github.io/book-edge/
+
+3) "Book-beta" tracks the tip of the beta branch and updates automatically.
+https://solana-labs.github.io/book-beta/
+
+To manually trigger an update of the "Book", create a new job of the manual-update-book pipeline.
+Set the tag of the latest release as the PUBLISH_BOOK_TAG environment variable.
+```bash
+PUBLISH_BOOK_TAG=v0.16.6
+```
+https://buildkite.com/solana-labs/manual-update-book
+
 ### Update software on testnet.solana.com
 
 The testnet running on testnet.solana.com is set to use a fixed release tag
@@ -145,12 +170,6 @@ TESTNET_TAG=[same value as used in TESTNET_TAG in the schedules]
 TESTNET_OP=create-and-start
 ```
 
-#### Update documentation
-
-Document the new recommended version by updating
-```export SOLANA_RELEASE=[new scheduled TESTNET_TAG value]```
-in book/src/testnet-participation.md for both edge and beta channel branches.
-
 ### Alert the community
 
 Notify Discord users on #validator-support that a new release for
diff --git a/ci/publish-book.sh b/ci/publish-book.sh
index 2a587774e..c286156af 100755
--- a/ci/publish-book.sh
+++ b/ci/publish-book.sh
@@ -2,6 +2,47 @@
 set -e
 
 cd "$(dirname "$0")/.."
+BOOK="book"
+
+eval "$(ci/channel-info.sh)"
+
+if [[ -n $PUBLISH_BOOK_TAG ]]; then
+  CURRENT_TAG="$(git describe --tags)"
+  COMMIT_TO_PUBLISH="$(git rev-list -n 1 "${PUBLISH_BOOK_TAG}")"
+
+  # book is manually published at a specified release tag
+  if [[ $PUBLISH_BOOK_TAG != "$CURRENT_TAG" ]]; then
+    (
+      cat <<EOF
+steps:
+  - trigger: "$BUILDKITE_PIPELINE_SLUG"
+    async: true
+    build:
+      message: "$BUILDKITE_MESSAGE"
+      commit: "$COMMIT_TO_PUBLISH"
+      env:
+        PUBLISH_BOOK_TAG: "$PUBLISH_BOOK_TAG"
+EOF
+    ) | buildkite-agent pipeline upload
+    exit 0
+  fi
+  repo=git@github.com:solana-labs/book.git
+else
+  # book-edge and book-beta are published automatically on the tip of the branch
+  case $CHANNEL in
+  edge)
+    repo=git@github.com:solana-labs/book-edge.git
+    ;;
+  beta)
+    repo=git@github.com:solana-labs/book-beta.git
+    ;;
+  *)
+   echo "--- publish skipped"
+   exit 0
+   ;;
+  esac
+  BOOK=$CHANNEL
+fi
 
 book/build.sh
 
@@ -16,22 +57,7 @@ echo --- create book repo
   git commit -m "${CI_COMMIT:-local}"
 )
 
-eval "$(ci/channel-info.sh)"
-# Only publish the book from the edge and beta channels for now.
-case $CHANNEL in
-edge)
-  repo=git@github.com:solana-labs/book-edge.git
-  ;;
-beta)
-  repo=git@github.com:solana-labs/book.git
-  ;;
-*)
- echo "--- publish skipped"
- exit 0
- ;;
-esac
-
-echo "--- publish $CHANNEL"
+echo "--- publish $BOOK"
 cd book/html/
 git remote add origin $repo
 git fetch origin master