Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Knowledge Base — DOCX/Google Drive Pipeline Retirement (2026-06)

TL;DR

The knowledge-base repo used to convert every markdown doc to DOCX and upload it to Google Drive, driven by a husky pre-commit hook. That entire pipeline was retired in June 2026 (knowledge-base PRs #246, #247). Markdown in src/ is the single source of truth — the Relay Slack bot reads it directly via a Bedrock Knowledge Base, and nobody consumed the Drive copies anymore.

If you find references to husky, pandoc, dist/docs, DOCX conversion, or Google Drive upload in this repo’s docs or tooling, they are stale — fix them.

What the old pipeline was

Three overlapping mechanisms, all producing/uploading DOCX:

  1. husky pre-commit hook (.husky/pre-commit) — on every local commit: generated PlantUML SVGs against a local Docker server at localhost:8080, converted staged markdown to DOCX with pandoc into dist/docs/, then ran git add on the entire repo root.
  2. build-docs.yml — on push to main: regenerated all diagrams, converted all markdown to DOCX, uploaded DOCX to Google Drive, committed SVGs + a tracking CSV back.
  3. upload-docs-to-drive.yml — on pushes touching dist/docs/**: re-uploaded DOCX to Drive and committed the tracking CSV back.

Why it was retired

  • The consumer disappeared. The Drive DOCX copies existed for humans/an older bot. The Relay Slack bot reads markdown directly: .github/workflows/sync-to-bedrock-kb.yml syncs src/**/*.md to S3 (relay-kb-docs-prod-512438352490) and triggers Bedrock KB ingestion. DOCX was dead weight.
  • The hook made committing painful and unsafe. It required Docker + PlantUML server + pandoc locally; when the server wasn’t running, curl -s wrote error output into the .svg files; and the final git add <repo root> staged unrelated/untracked files, making partial commits impossible.
  • Repo bloat. 903 generated .docx binaries (566 MB of working tree) were committed to git.
  • Race conditions. Both workflows committed the tracking CSV back to main independently, causing recurring push conflicts.

What replaced it

ConcernNow handled by
Slack bot document sourcesync-to-bedrock-kb.yml (markdown → S3 → Bedrock KB ingestion)
PlantUML SVG generationgenerate-diagrams.yml on push to main (CI commits SVGs back)
Markdown qualitypr-checks.yml on PRs — markdownlint + offline link check (blocking), SUMMARY.md / missing-H1 guards (warnings)
Local diagram preview (optional)bin/run_plantuml_server_docker.sh — see bin/README.md

Contributing now requires no local tooling: edit markdown, open a PR.

Deliberate decisions (don’t undo these casually)

  • No git history rewrite. The old DOCX packs (~1 GB) remain in history; rewriting would invalidate every clone for marginal benefit. The bloat simply stops growing.
  • External URLs are not link-checked in PRs. Only internal/relative links are verified (lychee --offline) — external checks make PRs flaky.
  • Lint rules are minimal on purpose. Several src/ directories are mirrored verbatim from other repos by the sync-*-docs.yml workflows; stylistic lint would fail PRs over content people didn’t write.

Cleanup checklist after PR #246

  • Delete repo secrets GOOGLE_DRIVE_CREDENTIALS and GOOGLE_DRIVE_FOLDER_ID (Settings → Secrets — needs admin). Done 2026-07-01 — both secrets already absent from gh secret list (current secrets: CLOUDFLARE_VENDOR_HUB_DEPLOY_HOOK_*, PAT_TOKEN, SLACK_WEBHOOK_DOCS_ALERTS).

  • Existing clones: git config --unset core.hooksPath (husky set it locally; harmless if left — the hooks no longer exist). Done 2026-07-01 — but the doc’s “harmless if left” line was wrong: .husky/_/ still held 4 git-lfs hooks (post-checkout, post-commit, post-merge, pre-push). Naive unset would have broken LFS for the repo’s .mp4 / .mov / .webm files. Proper migration:

    ```bash
git lfs install --local          # writes LFS hooks into .git/hooks/
git config --unset core.hooksPath
```

After this, `core.hooksPath` is empty and LFS hooks run from the
canonical `.git/hooks/` location. Per-clone housekeeping — each
engineer's local clone runs this once.

  • The Google Drive folder itself (https://drive.google.com/drive/u/0/folders/0APjft64d1c58Uk9PVA) — deleted 2026-07-01 per team confirmation. Cleanup checklist complete.

Stale references fixed (2026-07-01)

The doc warned: “If you find references to husky, pandoc, dist/docs, DOCX conversion, or Google Drive upload in this repo’s docs or tooling, they are stale — fix them.” PR #246 cleaned the workflows and .husky/pre-commit but missed these survivors. Removed in this commit:

  • .devcontainer/setup.sh — dropped the pandoc download/install block, the pandoc --version verify line, and the post-setup banner lines advertising convert_md_to_docx.sh / convert_docs_precommit.sh.
  • .devcontainer/README.md:
    • Removed “Husky for Git hooks” and the dedicated Pandoc feature line from the “What’s Included” list.
    • Dropped “Install Pandoc” and “Install Git hooks for automatic conversions” from the setup-script behaviour list.
    • Rewrote the PlantUML section: SVG generation is CI-driven (generate-diagrams.yml on push to main); the local PlantUML server is for optional preview only.
    • Deleted the entire “Document Conversion” section (auto + manual pandoc/.docx instructions, dist/docs/ outputs, references to the since-removed bin/convert_*.sh scripts).
    • Removed the .husky/ and stale bin/convert_*.sh entries from the file-structure tree, and the dist/docs/ line.
    • Removed the “Document conversion not working” troubleshooting block (pandoc install hint, pre-commit hook claim).

The devcontainer itself stays — devcontainer.json (Rust + mdBook + PlantUML server + node + git-lfs + dind) is still the supported local preview workflow per bin/README.md.

References