From bcd9b27cfebd3aa9423e93dff1ce4ab490252ef9 Mon Sep 17 00:00:00 2001 From: Thang Nguyen Date: Fri, 13 Nov 2026 16:51:23 +0700 Subject: [PATCH] docs: release checklist and the yourssh-docs-sync skill (docs site, release notes, Homebrew) --- .claude/skills/yourssh-docs-sync/SKILL.md | 43 +++++++++++++++++++++++ CLAUDE.md | 7 ++++ 2 files changed, 50 insertions(+) create mode 100644 .claude/skills/yourssh-docs-sync/SKILL.md diff --git a/.claude/skills/yourssh-docs-sync/SKILL.md b/.claude/skills/yourssh-docs-sync/SKILL.md new file mode 100644 index 00000000..f6ac811b --- /dev/null +++ b/.claude/skills/yourssh-docs-sync/SKILL.md @@ -0,0 +1,43 @@ +--- +name: yourssh-docs-sync +description: Use before every YourSSH release, or when the user asks to update the documentation site for recent changes — e.g. "cập nhật docs", "sync docs", "docs cho bản mới", "trước khi release". Updates the YoursshLabs/docs Mintlify site (https://yoursshlabs.com) so it matches the app on develop. +--- + +# yourssh-docs-sync + +The documentation site lives in a separate repo, **YoursshLabs/docs** (Mintlify, served at https://yoursshlabs.com). Two layers keep it current: + +1. **Automatic — release notes.** `release-notes.mdx` is generated from this repo's `CHANGELOG.md` by the docs repo's `.github/workflows/release-notes.yml` (every 6 hours, on demand, or on a `yourssh-release` repository dispatch). Nothing to write by hand: a good CHANGELOG entry *is* the release note. +2. **Manual (this skill) — the guides.** User-visible behaviour, labels, screenshots and new features must be reflected in the user and developer guides **before** the release PR is merged. + +## When + +Run it on the release branch (or `develop`) before opening the release PR to `master`. A release isn't done until the docs PR is merged. + +## Steps + +1. **Scope the changes.** `git fetch --tags`; `prev=$(git describe --tags --abbrev=0 origin/master)`; list `git log --oneline $prev..HEAD` and `git diff --stat $prev..HEAD -- app/lib packages`. Keep the user-visible ones: new or changed screens, labels, shortcuts, defaults, behaviour, security behaviour, platforms, install steps. Ignore pure refactors and tests. +2. **Map changes to pages.** Clone or update the docs repo (`gh repo clone YoursshLabs/docs` or `git -C pull`), branch `docs/sync-`. Use this map (docs path → app area): + + | Docs page | App area | + |---|---| + | `index.mdx`, `installation.mdx`, `quickstart.mdx` | platforms, release assets (`release.yml`), Homebrew tap, first launch, updater | + | `user-guide/hosts.mdx`, `host-keys.mdx`, `bulk-actions.mdx` | `widgets/hosts_dashboard*`, `host_detail_panel/`, `host_chain_editor.dart`, known hosts, `bulk/` | + | `user-guide/terminal.mdx`, `terminal-sharing.mdx` | `terminal_view.dart`, `session_tab*`, header/status bar, splits, search, input bar, shell integration, `HotkeyService`, share | + | `user-guide/sftp.mdx`, `port-forwarding.mdx` | SFTP screens, `entry_context_menu.dart`, transfers, code editor; port-forward screen/service | + | `user-guide/rdp.mdx`, `vnc.mdx` | RDP/VNC workspaces, cert trust, fullscreen | + | `user-guide/keychain.mdx`, `recording.mdx`, `audit-log.mdx` | keychain screen, `KeyProvider`, credential storage, recordings, audit | + | `user-guide/snippets.mdx`, `ai-chat.mdx`, `devops.mdx`, `web-tools.mdx`, `cli.mdx` | plugin packages, AI chat, `packages/yourssh_cli`, `services/cli/`, URL scheme | + | `user-guide/settings.mdx`, `sync.mdx`, `mobile.mdx` | `widgets/settings/`, sync services, `app/lib/mobile/` | + | `developer-guide/*` | `CLAUDE.md`, build/CI, plugin system, `docs/plugin-authoring-guide.md` | + +3. **Edit the pages.** Follow the docs repo's `AGENTS.md` (style, terminology, components). Check every bold UI label against the code. Document what develop does, not what a plan says. New pages must be added to `docs.json` navigation. +4. **Refresh screenshots for changed screens.** Use the `yourssh-screenshots` skill (`tool/docs_journey.sh setup`, then `SECTIONS= tool/docs_journey.sh run` for the affected sections, then `teardown`). Copy the new PNGs into the docs repo's `images//` with `sips -Z 1440`; keep the same file names so existing references keep working. Never publish a shot with a real host, IP, user name or secret (QR codes must carry `192.0.2.10`). +5. **Validate.** In the docs clone: `npx mint validate` and `npx mint broken-links` (both must pass; CI runs the same). +6. **Open the docs PR** against `main` of YoursshLabs/docs. Its required check **Build and check** must be green; merge it (merging deploys the site). +7. **After the app release is published,** trigger the release notes right away instead of waiting for the 6-hour schedule: `gh workflow run release-notes.yml -R YoursshLabs/docs`, then check https://yoursshlabs.com/release-notes shows the new version. + +## Don't + +- Don't hand-edit `release-notes.mdx` (it is regenerated; fix `CHANGELOG.md` instead). +- Don't merge the release PR to `master` while the docs PR for that release is still open. diff --git a/CLAUDE.md b/CLAUDE.md index 35c1ef23..00535d27 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,6 +32,13 @@ cd app && flutter test --name "pattern" # filter by test n - `flutter analyze` runs with `--no-fatal-infos` in CI: on 3.50 about 214 infos are `package:flutter/material.dart` deprecations (the material_ui migration is a separate task). Warnings and errors still fail. - Flutter (3.47 and later) migrates project files on its own, and those changes are committed so builds leave the tree clean. `pub get` adds `build/**` and the platform folders to `analyzer.exclude` in `app/analysis_options.yaml`. `flutter build macos` raises the macOS deployment target to 12.0 (`Podfile`, `project.pbxproj`) and moves the plugins that support Swift Package Manager out of `Podfile.lock`. +## Releases + +`develop` → branch `release/X.Y.Z` (bump `app/pubspec.yaml` `version`, date the CHANGELOG section) → PR to `master` → merge runs `.github/workflows/release.yml` (signed + notarized macOS DMG/zip, Windows x64/arm64, Linux x86_64/arm64, Android, GitHub release `vX.Y.Z`) → replace the auto-generated release notes with the CHANGELOG section → PR `master` → `develop` to sync the version. Checklist: +- **Docs first:** run the `yourssh-docs-sync` skill and merge its YoursshLabs/docs PR before merging the release PR. Site: https://yoursshlabs.com (Mintlify, repo YoursshLabs/docs; `main` takes PRs with a green "Build and check"). +- **Release notes on the site are automatic:** the docs repo's `release-notes.yml` regenerates `release-notes.mdx` from this CHANGELOG at the latest tag (every 6 h; `gh workflow run release-notes.yml -R YoursshLabs/docs` to run it now). Write the CHANGELOG for users — it is the published release note. +- **Homebrew:** `YoursshLabs/homebrew-tap` (`brew install --cask yoursshlabs/tap/yourssh`) bumps its cask from the latest release every 6 h (`gh workflow run update-cask.yml -R YoursshLabs/homebrew-tap` to run it now). + ## App icon Every platform icon is generated from the vector masters in `assets/branding/` —