Merge pull request #16 from metabase/branchname-aware-docs-building

Author: escherize

.github/workflows/process_docs_changes.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set current branch name
-        run: echo "LOCAL_REPO_BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_ENV
+        run: echo "LOCAL_REPO_BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> "$GITHUB_ENV"
 
       - name: echo branch name
         run: |
@@ -35,7 +35,7 @@ jobs:
 
       - name: Filter non-documented branches
         run: |
-          bb script/check_incoming_branchname.clj $MAIN_REPO_BRANCH
+          bb script/check_incoming_branchname.clj "$MAIN_REPO_BRANCH"
 
       - name: Install js dependencies
         run: yarn install --frozen-lockfile --prefer-offline
@@ -49,10 +49,12 @@ jobs:
         run: |
           bundle install
 
+      - name: Update docs for branchname
+        run: |
+          bb script/update_docs_for_branchname.clj "$MAIN_REPO_BRANCH"
+
       - name: Update docs
         run: |
-          # ./script/docs-update
-          # ./script/docs master --set-version master
           ./script/docs "$MAIN_REPO_BRANCH" --set-version "$MAIN_REPO_BRANCH"
 
       - name: "Lint the markdown"
@@ -81,21 +83,21 @@ jobs:
           # Build the jekyll site:
           JEKYLL_ENV=development bundle exec jekyll build --baseurl '' --config _config.docs.yml --trace
 
-      - name: "Check all of the links"
+      - name: Run metabase.com-aware link checks
         run: |
           script/links || true
           echo 'checking reported links...'
-          echo "htmlproofer spit out a report of length: $(cat htmlproofer.out | wc -l)"
+          echo "htmlproofer spit out a report of length: $(wc -l < htmlproofer.out)"
           bb script/analyze_links.clj --htmlproofer-output htmlproofer.out
 
-      - name: Authenticate Git with GITHUB_TOKEN
+      - name: Setup Git Authenticatation
         run: |
           git config --global user.name "Metabase Docs bot"
           git config --global user.email "metabase-bot@metabase.com"
           git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/metabase/docs.metabase.github.io.git"
 
-      - name: Create the pull request
+      - name: Update or Create the Pull Request
         env:
           GH_TOKEN: ${{ secrets.METABASE_AUTOMATION_USER_TOKEN }}
         run: |
-          bb script/update_or_create_pr.clj $MAIN_REPO_BRANCH
+          bb script/update_or_create_pr.clj "$MAIN_REPO_BRANCH"

_config.yml

@@ -11,19 +11,19 @@ default_social_image: /images/twitter/default.png
 redcarpet:
     extensions: [no_intra_emphasis, fenced_code_blocks, autolink, tables, with_toc_data]
 plugins:
-  - jekyll-redirect-from
+    - jekyll-redirect-from
 whitelist:
-  - jekyll-redirect-from
-  - jekyll_include_plugin
-  - jekyll_dirname_payload_plugin
+    - jekyll-redirect-from
+    - jekyll_include_plugin
+    - jekyll_dirname_payload_plugin
 jekyll_include_plugin:
-  snippet_prefix: ''
+    snippet_prefix: ""
 sass:
-  sass_dir: _sass
-  style: compressed
+    sass_dir: _sass
+    style: compressed
 permalink: '/blog/:title'
 webrick:
-  headers: {X-Frame-Options: deny, Content-Security-Policy: 'frame-ancestors ''none'''}
+    headers: {X-Frame-Options: deny, Content-Security-Policy: 'frame-ancestors ''none'''}
 java-minimum-version: 21
 latest_version: v0.53.8
 latest_enterprise: v1.53.8

bb.edn

@@ -1 +1,3 @@
-{}
+{:paths ["script"]
+ :deps {org.babashka/cli {:mvn/version "0.8.65"}
+        io.github.paintparty/bling {:mvn/version "0.5.0"}}}

script/check_incoming_branchname.clj

@@ -1,24 +1,12 @@
 (ns check-incoming-branchname
-  (:require [clojure.string :as str]))
+  (:require
+   [util :as u]
+   [clojure.string :as str]))
 
 (defn usage []
   (println "Usage: script/check_incoming_branchname.clj branchname")
   (System/exit 1))
 
-(def release-regex #"release-x\.(\d+)\.x")
-
-(defn extract-release-num [release-branchname]
-  (let [[_ num] (re-matches release-regex release-branchname)]
-    num))
-
-(defn categorize-branchname [branchname]
-  (cond
-    (= branchname "master") [:master]
-    (re-matches release-regex branchname) [:release (extract-release-num branchname)]
-    (or
-      (= branchname "doc-update-detection")
-      (str/starts-with? branchname "docs-workflow-test-")) [:test branchname]))
-
 (defn -main
   "This is called from the `process_docs_changes.yml` workflow. It checks that
    the branchname is either `master` or a release branch. If not, it exits with
@@ -27,7 +15,7 @@
   [& args]
   (let [branchname (or (first args) (usage))
         _ (println "Checking branchname:" branchname)
-        [category release-num] (categorize-branchname branchname)]
+        [category release-num] (u/categorize-branchname branchname)]
     (case category
       :master (println "Master branch detected.")
       :release (println "Release branch detected. Release number: " release-num)

script/update_docs_for_branchname.clj

@@ -0,0 +1,58 @@
+(ns update-docs-for-branchname
+  (:require
+   [babashka.process :as p]
+   [bling.core :refer [bling callout]]
+   [clj-yaml.core :as yaml]
+   [util :as u]))
+
+;; TODO: add test that docs_version is always parsable
+
+(defn config-docs-version
+  "Get the latest docs version number from the _config.yml file."
+  []
+  (let [[_ version-num] (re-matches #"v0.(\d+)" (:docs_version (yaml/parse-string (slurp "_config.yml"))))]
+    (Integer/parseInt version-num)))
+
+(defn update? [config-docs-version release-num]
+  (cond
+    (> release-num config-docs-version)
+    (do
+      (callout {:type :warning
+                :label "Newer version detected"}
+               (format "Release number from branch (%s) is newer than docs_version from config.yml (%s).\nContinuing build."
+                       release-num
+                       config-docs-version))
+      false)
+
+    (= release-num config-docs-version)
+    true
+
+    :else false))
+
+(defn usage []
+  (println "Usage: script/update_docs_for_branchname.clj branchname")
+  (System/exit 1))
+
+(defn -main [& args]
+  (let [branchname (first args)
+        dry-run? (contains? (set args) "--dry-run")
+        _ (when (nil? branchname)
+            (println (callout {:type :error} (bling [:red "No branchname provided."])))
+            (usage))
+        [category release-num] (u/categorize-branchname branchname)
+        command (case category
+                  :master "./script/docs master --set-version master"
+                  :release (format "./script/docs release-x.%s.x --set-version v0.%s %s"
+                                   release-num
+                                   release-num
+                                   (if (update? (config-docs-version) release-num)
+                                     "--update"
+                                     ""))
+                  :test (format "./script/docs %s --set-version %s" branchname branchname)
+                  (do (println "Unpublishable branchname: " branchname)
+                      (System/exit 1)))]
+    (callout {:type :info :label "Command To Run"} (bling [:green command]))
+    (when-not dry-run? (p/shell command))))
+
+(when (= *file* (System/getProperty "babashka.file"))
+  (apply -main *command-line-args*))

script/util.clj

@@ -0,0 +1,16 @@
+(ns util
+  (:require [clojure.string :as str]))
+
+(def release-regex #"release-x\.(\d+)\.x")
+
+(defn- extract-release-num [release-branchname]
+  (let [[_ num] (re-matches release-regex release-branchname)]
+    (Integer/parseInt num)))
+
+(defn categorize-branchname [branchname]
+  (cond
+    (= branchname "master") [:master]
+    (re-matches release-regex branchname) [:release (extract-release-num branchname)]
+    (or
+      (= branchname "doc-update-detection")
+      (str/starts-with? branchname "docs-workflow-test-")) [:test branchname]))