Merge pull request #839 from Yacht-sh/WY-code/wiki-refresh

wickedyoda · web-flow · commit 0f65b6208466 · 2026-03-28T23:33:20.000-05:00
Add wiki snapshot for current develop operations
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ The rewrite effort is being explored in [Yacht-sh/yacht-nuxt](https://github.com
 The installation docs currently live at [dev.yacht.sh](https://dev.yacht.sh).
 
 Repo-local documentation now lives in [`docs/`](./docs/README.md).
+Operational wiki pages for the current `develop` branch live in [`wiki/`](./wiki/Home.md).
 
 ## Demo
 
diff --git a/docs/README.md b/docs/README.md
@@ -13,6 +13,8 @@ This directory contains the repo-local documentation for the current Yacht imple
 - [CI/CD and Image Publishing](./ci-cd.md)
 - [Security Guide](./security.md)
 
+The repo also keeps a lightweight operational wiki snapshot in [`../wiki/`](../wiki/Home.md) for current branch workflow, dependency compatibility, verification, and GHCR publishing notes.
+
 ## Scope
 
 These docs describe the code that exists in this repository today, including:
diff --git a/wiki/Dependency-Compatibility.md b/wiki/Dependency-Compatibility.md
@@ -0,0 +1,50 @@
+# Dependency Compatibility
+
+This page records the dependency decisions that currently keep `develop` working.
+
+## Backend
+
+Current noteworthy backend pins from [`../backend/requirements.txt`](../backend/requirements.txt):
+
+- `fastapi==0.120.4`
+- `pydantic==1.10.22`
+- `aiostream==0.7.1`
+- `idna==3.11`
+- `makefun==1.16.0`
+- `pycparser==3.0`
+- `cryptography==46.0.6`
+
+### Important Rule
+
+`fastapi` is intentionally pinned to `0.120.4` because the current backend remains on Pydantic v1.
+
+Do not bump FastAPI independently unless you are also doing the backend migration required for newer Pydantic expectations and verifying the entire API/auth stack.
+
+## Frontend
+
+Current noteworthy frontend versions from [`../frontend/package.json`](../frontend/package.json):
+
+- `vue: ^2.7.16`
+- `vuetify: ^2.7.2`
+- `vue-chartjs: ^3.5.1`
+- `@mdi/font: ^7.4.47`
+- `sass: ^1.98.0`
+- `@vue/eslint-config-prettier: ^6.0.0`
+- `prettier: ^1.19.1`
+
+### Important Rules
+
+- keep `vue-chartjs` on the Vue 2 compatible line
+- keep `@vue/eslint-config-prettier` on the ESLint 6 compatible line
+- do not assume grouped frontend dependency PRs are safe to merge without verification, especially when they touch Vue, Vuetify, ESLint, or formatting tooling
+
+## How To Handle Future Dependency PRs
+
+1. Merge or cherry-pick the dependency PR into a topic branch off `develop`.
+2. Run the verification commands from the runbook.
+3. If the update is incompatible:
+   - keep the merge history if desired
+   - add a follow-up compatibility commit that restores the known-good version
+   - document the reason here
+
+This approach keeps the repo history honest while preserving a working branch.
diff --git a/wiki/Development-And-Release-Flow.md b/wiki/Development-And-Release-Flow.md
@@ -0,0 +1,33 @@
+# Development And Release Flow
+
+## Branch Roles
+
+- `master` is the default branch and production-oriented release line.
+- `develop` is the integration branch for ongoing dependency, workflow, and feature work.
+
+## Expected Flow
+
+1. Start feature or maintenance work from `develop`.
+2. Push that work on a topic branch.
+3. Open a PR into `develop`.
+4. After `develop` is verified, open or update the `develop -> master` PR.
+
+## Protected Branch Notes
+
+- `develop` is protected.
+- Do not assume you can force-push rebased history back to `develop`.
+- If you rebase locally for cleanup, you may still need to merge the current `origin/develop` tip back in before the final push can succeed as a normal fast-forward update.
+
+## PR Integration Notes
+
+When merging multiple dependency PRs into `develop`:
+
+- merge the PR branches into `develop`
+- run verification immediately after the merge set
+- keep the merge history if it helps preserve the audit trail for which PRs were absorbed
+- make one follow-up compatibility commit if the merged dependency set needs corrective pins
+
+## Current Release Notes Worth Remembering
+
+- the main image publish workflow now targets `linux/amd64` and `linux/arm64`
+- `linux/arm/v7` was removed from the main image publish path because it required unsupported dependency build work for this branch
diff --git a/wiki/Home.md b/wiki/Home.md
@@ -0,0 +1,24 @@
+# Yacht Wiki
+
+This wiki folder captures the current operational state of the `develop` branch.
+
+It is intentionally practical. These pages document the branch flow, CI checks, dependency compatibility rules, and image publishing prerequisites that are easy to lose during day-to-day work.
+
+## Pages
+
+- [Development And Release Flow](./Development-And-Release-Flow.md)
+- [Verification Runbook](./Verification-Runbook.md)
+- [Dependency Compatibility](./Dependency-Compatibility.md)
+- [Image Publishing And GHCR](./Image-Publishing-And-GHCR.md)
+
+## Current Snapshot
+
+- default branch: `master`
+- integration branch: `develop`
+- main application image platforms: `linux/amd64`, `linux/arm64`
+- frontend stack: Vue 2 + Vuetify 2
+- backend API stack: FastAPI with Pydantic v1 compatibility preserved
+
+## Why This Exists
+
+Recent work on `develop` merged a large set of dependency and workflow updates. Some of those updates were compatible as-is, and some required explicit pins to keep the codebase working. The pages in this folder record those decisions so future dependency and CI work starts from the current known-good state instead of rediscovering it.
diff --git a/wiki/Image-Publishing-And-GHCR.md b/wiki/Image-Publishing-And-GHCR.md
@@ -0,0 +1,62 @@
+# Image Publishing And GHCR
+
+## Current Workflow
+
+The image publish workflow is defined in [`../.github/workflows/build.yml`](../.github/workflows/build.yml).
+
+Main points:
+
+- runs on pushes to `master` and `develop`
+- verifies frontend, backend, and agent before publishing
+- publishes the main Yacht image for:
+  - `linux/amd64`
+  - `linux/arm64`
+- publishes the agent image separately
+
+## Current Tag Behavior
+
+On `master`:
+
+- main image channel tag: `latest`
+- version tag: UTC timestamp
+
+On `develop`:
+
+- main image channel tag: `dev-latest`
+- version tag: `dev-<timestamp>`
+
+## GHCR Login Behavior
+
+The workflow logs into GHCR with:
+
+- `GHCR_USERNAME` / `GHCR_TOKEN` if they are configured
+- otherwise `github.actor` / `GITHUB_TOKEN`
+
+## Known GHCR Failure Mode
+
+If the build succeeds but push fails with a blob `HEAD` request returning `403 Forbidden`, the problem is usually package permission scope, not Docker build content.
+
+Typical causes:
+
+- the existing `ghcr.io/yacht-sh/yacht` package is not linked to the `Yacht-sh/Yacht` repository
+- the repository has not been granted package access
+- the fallback `GITHUB_TOKEN` does not have the effective package permissions needed for that existing package namespace
+- a PAT is being used without the required `read:packages` and `write:packages` scopes
+
+## What To Check In GitHub
+
+1. Open the `ghcr.io/yacht-sh/yacht` package settings.
+2. Ensure the `Yacht-sh/Yacht` repository has access to the package.
+3. If using a PAT, ensure it has:
+   - `read:packages`
+   - `write:packages`
+4. If the org uses SSO, authorize the token for the org.
+
+## Platform Notes
+
+The main image publish path no longer targets `linux/arm/v7`.
+
+Reason:
+
+- that path required unsupported dependency build work for the current branch
+- `linux/amd64` and `linux/arm64` are the current maintained publish targets
diff --git a/wiki/Verification-Runbook.md b/wiki/Verification-Runbook.md
@@ -0,0 +1,69 @@
+# Verification Runbook
+
+This page records the checks that match the current repository workflows and the local commands that were used to verify the current `develop` branch.
+
+## CI Workflow Summary
+
+The main build workflow is [`../.github/workflows/build.yml`](../.github/workflows/build.yml).
+
+It currently runs:
+
+- frontend install, lint, audit, and production build
+- backend dependency install, `pip check`, `compileall`, Bandit, and `pip-audit`
+- agent dependency install, `compileall`, Bandit, and `pip-audit`
+- image publishing after verification succeeds
+
+## Frontend Local Verification
+
+Use Docker to avoid host Node drift:
+
+```bash
+docker run --rm -v "$PWD/frontend:/app" -w /app node:20-bookworm-slim \
+  bash -lc 'npm ci --legacy-peer-deps --no-audit --no-fund && npm run lint && npm run build'
+```
+
+Expected result:
+
+- `npm run lint` may emit warnings
+- the command should still exit successfully
+- `npm run build` should complete and produce `frontend/dist`
+
+## Backend Local Verification
+
+Fast local checks:
+
+```bash
+python3 -m compileall backend
+bandit -q -r backend/api
+```
+
+Containerized dependency audit with native build packages:
+
+```bash
+docker run --rm -v "$PWD/backend:/app" -w /app python:3.11-slim \
+  bash -lc 'apt-get update >/tmp/apt.log && \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+      build-essential pkg-config libffi-dev libssl-dev libpq-dev \
+      default-libmysqlclient-dev libjpeg-dev zlib1g-dev libyaml-dev >/tmp/apt-install.log && \
+    python -m pip install --no-cache-dir pip-audit >/tmp/pip-audit-install.log && \
+    pip-audit -r requirements.txt --progress-spinner=off'
+```
+
+Expected result:
+
+- `No known vulnerabilities found`
+
+## Agent Local Verification
+
+The CI workflow verifies the agent separately. Follow the same pattern as the backend:
+
+- install `agent/requirements.txt`
+- run `python -m compileall agent`
+- run `bandit -q -r agent`
+- run `pip-audit -r agent/requirements.txt --progress-spinner=off`
+
+## When Verification Fails
+
+- fix the dependency or workflow problem first
+- do not document a change as current behavior until the branch verifies cleanly
+- if a dependency bump is incompatible with the current codebase, pin it back to the last known-good version and document why in the compatibility page
