docs: finalize release docs
This commit is contained in:
Ogulcan Celik
parent
8c6a9e1f65
commit
faaddfe18d
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
name: herdr-pre-release-audit
|
||||
description: Audit herdr release readiness by comparing commits since the base release against next-release changelog and docs. Use when asked to run or apply the repo's pre-release audit, validate docs/next before release, inspect issue refs that release CI will close, or finalize release docs for herdr.
|
||||
---
|
||||
|
||||
# Herdr Pre-release Audit
|
||||
|
||||
Use this skill only inside the herdr repository.
|
||||
|
||||
Read `references/pre-release-audit.md` and follow its workflow. Treat it as the source of truth for:
|
||||
|
||||
- choosing the release base ref
|
||||
- inspecting first-parent history and merged PRs
|
||||
- auditing `docs/next/CHANGELOG.md`
|
||||
- auditing `docs/next/README.md` and staged website docs
|
||||
- checking issue reference lines
|
||||
- deciding when to run `just release-docs-check`
|
||||
- producing the final release-readiness report
|
||||
|
||||
Do not edit files during the audit unless the user explicitly asks to apply fixes. When applying fixes, keep changes scoped to the files named in the reference workflow.
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
description: Audit next-release docs and changelog before release
|
||||
---
|
||||
Audit release readiness for this repo.
|
||||
|
||||
Optional starting ref override: `$1`
|
||||
Extra user intent/context: `${@:2}`
|
||||
|
||||
Process:
|
||||
|
||||
1. Determine the base ref.
|
||||
- If `$1` is non-empty and looks like a ref/tag, use it.
|
||||
- Otherwise use the latest release tag, preferring the repo's semver tag style:
|
||||
```bash
|
||||
git describe --tags --abbrev=0
|
||||
```
|
||||
|
||||
2. Inspect the range from base ref to `HEAD`.
|
||||
- Use first-parent history for release context:
|
||||
```bash
|
||||
git log --first-parent --reverse --format='%H%x09%s' <base>..HEAD
|
||||
```
|
||||
- Also inspect full commits and commit bodies when needed:
|
||||
```bash
|
||||
git log --reverse --format='%H%x09%s%n%b' <base>..HEAD
|
||||
```
|
||||
|
||||
3. Detect merged PRs if any.
|
||||
- Look for first-parent subjects that indicate PR merges, including squash merges like `title (#123)`.
|
||||
- If GitHub CLI is available and the PR number is known, use it to fetch PR title/body for context.
|
||||
- Treat a merged PR as the primary release unit.
|
||||
- Do **not** also list individual commits that belong to that PR.
|
||||
|
||||
4. Handle direct commits separately.
|
||||
- Any commit in the range not represented by a merged PR should be considered on its own.
|
||||
|
||||
5. Infer what matters.
|
||||
- For each PR or direct commit, inspect changed files and diff stats.
|
||||
- Read the most relevant files in full when needed to understand user-facing impact.
|
||||
- Ignore pure housekeeping unless it has release value:
|
||||
- version bumps
|
||||
- release/tag commits
|
||||
- changelog-only commits
|
||||
- formatting-only changes
|
||||
- comment-only/doc-only changes unless they materially affect users
|
||||
|
||||
6. Audit `docs/next/CHANGELOG.md` and issue references.
|
||||
- Treat root `CHANGELOG.md` as the latest released changelog.
|
||||
- Treat `docs/next/CHANGELOG.md` as the next-release changelog.
|
||||
- Compare meaningful user-facing changes in the commit range against `docs/next/CHANGELOG.md`.
|
||||
- Flag missing entries for new features, bug fixes, removals, breaking changes, defaults, compatibility changes, user-visible command/config/API behavior, and security-relevant changes.
|
||||
- Do not require changelog entries solely for internal client/server protocol version bumps. Mention protocol only when the release intentionally changes user-facing compatibility guidance beyond the normal restart requirement.
|
||||
- Inspect commit bodies for issue reference lines in the form `refs #<issue-number>`.
|
||||
- Flag normal commits that use GitHub closing keywords like `fixes #<issue-number>`, `closes #<issue-number>`, or `resolves #<issue-number>`, because they close issues before release when they land on `master`.
|
||||
- For each shipped issue reference, check whether the changelog has a matching user-facing entry that mentions `#<issue-number>` when appropriate.
|
||||
- For each merged external human PR, check whether the changelog entry mentions the PR number and thanks the contributor in the existing style, e.g. `(#129, thanks @username)`. If the PR primarily ships an issue fix, include both the issue and PR numbers when useful, e.g. `(#128, #129, thanks @username)`. Do not add thanks text for maintainer-owned bots or automation accounts such as `kangal-bot` or `dependabot`.
|
||||
- Do not require or add GitHub closing keywords like `fixes #<issue-number>`, `closes #<issue-number>`, or `resolves #<issue-number>` to changelog entries or release notes.
|
||||
- List shipped issue references under `Issue references to close after release:` so the release operator can verify what release CI will close after the GitHub Release is published.
|
||||
- Flag stale entries that do not appear to correspond to shipped changes in the range.
|
||||
- Flag entries that are too implementation-focused or unclear for end users.
|
||||
- Preserve the existing changelog style and sections: `Added`, `Changed`, `Fixed`, `Removed`, and `Breaking Changes` when applicable.
|
||||
|
||||
7. Audit next-release public docs.
|
||||
- Treat root `README.md` and `website/src/content/docs/` as the latest released public docs.
|
||||
- Treat `docs/next/README.md` as the next-release root README, and `docs/next/website/src/content/docs/` as the full next-release mirror of website docs.
|
||||
- Compare meaningful user-facing changes in the range against next-release docs first.
|
||||
- Flag missing release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes.
|
||||
- Compare `docs/next/README.md` against root `README.md`, and compare the staged website-doc mirror against `website/src/content/docs/`. Flag each difference as intended to ship in this release, stale, or needing user decision.
|
||||
- Also audit example config snippets for release readiness.
|
||||
|
||||
8. Verify finalization state.
|
||||
- Before `just release`, approved `docs/next/README.md` must be copied to root `README.md`, approved staged website docs must be copied from `docs/next/website/src/content/docs/` to `website/src/content/docs/`, and the deleted root doc files must stay deleted.
|
||||
- Run or recommend:
|
||||
```bash
|
||||
just release-docs-check
|
||||
```
|
||||
- This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, and exact 1:1 sync between `docs/next/website/src/content/docs/` and `website/src/content/docs/`.
|
||||
- Do not run `just release` unless the working tree is clean and the docs check passes.
|
||||
|
||||
9. Apply changes only when asked.
|
||||
- Do not edit files during the audit unless the user explicitly asks you to apply fixes.
|
||||
- When asked to apply audit fixes, update `docs/next/CHANGELOG.md`, `docs/next/README.md`, and any required staged website docs under `docs/next/website/src/content/docs/`.
|
||||
- When asked to finalize release docs, copy approved next-release README and changelog into root, copy approved staged website docs into `website/src/content/docs/`, then run `just release-docs-check`.
|
||||
|
||||
Output format:
|
||||
|
||||
```md
|
||||
Release readiness: READY | NOT READY
|
||||
|
||||
Base: <base ref>
|
||||
Range: <base ref>..HEAD
|
||||
Meaningful shipped changes: yes | no
|
||||
|
||||
Changelog: OK | MISSING ENTRIES | NEEDS ATTENTION
|
||||
Missing:
|
||||
- <only user-facing shipped changes missing from docs/next/CHANGELOG.md>
|
||||
|
||||
Docs: OK | MISSING | INACCURATE | NEEDS DECISION
|
||||
Missing:
|
||||
- <only required next-release public docs gaps>
|
||||
|
||||
Wrong or questionable:
|
||||
- <docs that disagree with implementation, if any>
|
||||
|
||||
Issue refs: OK | NEEDS ATTENTION
|
||||
Will close after release:
|
||||
- #<issue>
|
||||
|
||||
Accepted/no action:
|
||||
- <items the user explicitly accepted, such as known closing-keyword commits>
|
||||
|
||||
Root docs finalized: YES | NO
|
||||
<result of just release-docs-check or why it was not run>
|
||||
|
||||
Required before release:
|
||||
1. <short action>
|
||||
```
|
||||
|
||||
Keep the main output glanceable. Put commit inventories, excluded housekeeping, and commands run in an appendix only when they materially help the operator.
|
||||
|
||||
If the range has no meaningful user-facing changes, say that plainly instead of forcing entries.
|
||||
14
CHANGELOG.md
14
CHANGELOG.md
|
|
@ -2,6 +2,20 @@
|
|||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
- Added pane copy mode at `prefix+[` with keyboard navigation, visual selection, and clipboard yank support. (#231)
|
||||
- Added `foreground_cwd` to pane and agent API/CLI responses so integrations can inspect the active foreground process directory without changing the existing pane/workspace `cwd` semantics. (#345)
|
||||
- Added read-only `agent_session` metadata to pane and agent API/CLI responses when official integrations report native session references.
|
||||
|
||||
### Fixed
|
||||
- Live handoff now preserves terminal state when transferring supported running panes to a replacement server.
|
||||
- WSL clipboard writes now prefer OSC 52 before WSLg clipboard tools, so mouse selection and double-click copy populate Windows clipboard history in Windows Terminal. (#333)
|
||||
- Incomplete host terminal OSC default-color replies no longer get misread as Alt-key input and forwarded into panes, preventing interactive prompts such as `gh auth login --web` from aborting on split `ESC ]` input. (#279, #306, #344)
|
||||
- Workspace rename prompts and background notifications now use live cwd-derived workspace labels instead of stale session labels. (#332)
|
||||
- `herdr session stop` no longer fails on zero-duration socket timeouts when the stop deadline is nearly exhausted.
|
||||
- Update preview instructions now wrap long package-manager commands instead of truncating the shell command suffix.
|
||||
- Restored native agent resume panes now fall back to a shell when the resumed agent exits instead of closing the whole pane.
|
||||
|
||||
## [0.6.4] - 2026-05-27
|
||||
|
||||
### Fixed
|
||||
|
|
|
|||
|
|
@ -147,7 +147,7 @@ not a gui window, not a web dashboard, not electron. herdr runs inside whatever
|
|||
|
||||
- **workspaces** — organized around git repos or folder names, each with its own tabs and panes
|
||||
- **tabs** — first-class in the socket api and cli
|
||||
- **mouse-native** — click panes/tabs/workspaces/agents, drag borders, drag-select text to copy, double-click tokens to copy, right-click menus; not keyboard-only
|
||||
- **copy-friendly** — drag-select text, double-click tokens, or use keyboard copy mode with `prefix+[`, `h/j/k/l`, `{`/`}`, `v`, and `y`
|
||||
- **notifications** — sounds and toasts for background events; tab-aware suppression
|
||||
- **18 built-in themes** — catppuccin, terminal, tokyo night, gruvbox, one, solarized, kanagawa, rosé pine, vesper, and light variants for the main palettes
|
||||
- **session persistence** — pane processes survive client detach; sessions restore panes after full restart, with opt-in recent screen history
|
||||
|
|
@ -195,7 +195,7 @@ automatic detection works out of the box. process name matching plus terminal ou
|
|||
| antigravity cli | ✓ | ✓ | ✓ |
|
||||
| kimi code cli | ✓ | ✓ | ✓ |
|
||||
| [github copilot cli](https://github.com/features/copilot) | ✓ | ✓ | ✓ |
|
||||
| qoder cli | ✓ | ✓ | ✓ |
|
||||
| [qodercli](https://qoder.com/cli) | ✓ | ✓ | ✓ |
|
||||
| [kiro cli](https://kiro.dev/docs/cli/) | ✓ | ✓ | — |
|
||||
|
||||
detected but not fully tested: gemini cli, cline.
|
||||
|
|
@ -204,7 +204,7 @@ for agents outside the built-in list, herdr still works as a terminal multiplexe
|
|||
|
||||
### direct integrations
|
||||
|
||||
the built-in pi, omp, claude code, codex, opencode, hermes, and qoder cli integrations forward semantic state to herdr over the socket api. install with:
|
||||
the built-in pi, omp, claude code, codex, opencode, hermes, and qodercli integrations forward semantic state to herdr over the socket api. install with:
|
||||
|
||||
```bash
|
||||
herdr integration install pi
|
||||
|
|
@ -297,7 +297,7 @@ full logging and environment variable details: [configuration docs](https://herd
|
|||
## docs
|
||||
|
||||
- [configuration](https://herdr.dev/docs/configuration/) — keybindings, themes, notifications, environment variables
|
||||
- [integrations](https://herdr.dev/docs/integrations/) — pi, omp, claude code, codex, opencode, hermes, qoder cli integrations
|
||||
- [integrations](https://herdr.dev/docs/integrations/) — pi, omp, claude code, codex, opencode, hermes, qodercli integrations
|
||||
- [`SKILL.md`](./SKILL.md) — reusable agent skill
|
||||
- [socket api](https://herdr.dev/docs/socket-api/) — socket protocol and cli reference
|
||||
|
||||
|
|
|
|||
|
|
@ -5,10 +5,15 @@
|
|||
### Added
|
||||
- Added pane copy mode at `prefix+[` with keyboard navigation, visual selection, and clipboard yank support. (#231)
|
||||
- Added `foreground_cwd` to pane and agent API/CLI responses so integrations can inspect the active foreground process directory without changing the existing pane/workspace `cwd` semantics. (#345)
|
||||
- Added read-only `agent_session` metadata to pane and agent API/CLI responses when official integrations report native session references.
|
||||
|
||||
### Fixed
|
||||
- Live handoff now preserves terminal state when transferring supported running panes to a replacement server.
|
||||
- WSL clipboard writes now prefer OSC 52 before WSLg clipboard tools, so mouse selection and double-click copy populate Windows clipboard history in Windows Terminal. (#333)
|
||||
- Incomplete host terminal OSC default-color replies no longer get misread as Alt-key input and forwarded into panes, preventing interactive prompts such as `gh auth login --web` from aborting on split `ESC ]` input. (#279, #344)
|
||||
- Incomplete host terminal OSC default-color replies no longer get misread as Alt-key input and forwarded into panes, preventing interactive prompts such as `gh auth login --web` from aborting on split `ESC ]` input. (#279, #306, #344)
|
||||
- Workspace rename prompts and background notifications now use live cwd-derived workspace labels instead of stale session labels. (#332)
|
||||
- `herdr session stop` no longer fails on zero-duration socket timeouts when the stop deadline is nearly exhausted.
|
||||
- Update preview instructions now wrap long package-manager commands instead of truncating the shell command suffix.
|
||||
- Restored native agent resume panes now fall back to a shell when the resumed agent exits instead of closing the whole pane.
|
||||
|
||||
## [0.6.4] - 2026-05-27
|
||||
|
|
|
|||
|
|
@ -129,9 +129,15 @@ herdr pane report-agent <pane_id> \
|
|||
--state idle|working|blocked|unknown \
|
||||
[--message TEXT] \
|
||||
[--custom-status TEXT] \
|
||||
[--seq N]
|
||||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH]
|
||||
```
|
||||
|
||||
`pane get`, `pane list`, `agent get`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted.
|
||||
|
||||
Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The existing `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
|
||||
|
||||
Report display-only pane metadata without taking over semantic state:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -124,6 +124,7 @@ next_tab = "prefix+n"
|
|||
switch_tab = "prefix+1..9"
|
||||
rename_tab = "prefix+shift+t"
|
||||
close_tab = "prefix+shift+x"
|
||||
copy_mode = "prefix+["
|
||||
focus_pane_left = "prefix+h"
|
||||
focus_pane_down = "prefix+j"
|
||||
focus_pane_up = "prefix+k"
|
||||
|
|
|
|||
|
|
@ -53,6 +53,10 @@ Herdr is mouse-native. You can click panes, tabs, workspaces, and agents; drag b
|
|||
|
||||
Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. The portable terminal-native fallback is Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS.
|
||||
|
||||
## Copy from the keyboard
|
||||
|
||||
Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, `w/b/e`, and `{`/`}` to move, `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying.
|
||||
|
||||
## Manage named sessions
|
||||
|
||||
Named sessions are separate Herdr server namespaces. Use them when you want fully separate runtime state.
|
||||
|
|
|
|||
|
|
@ -163,6 +163,23 @@ Integrations report agent state with `pane.report_agent`.
|
|||
|
||||
`custom_status` is visual. It can show a short label like `indexing` without changing semantic behavior.
|
||||
|
||||
Official integrations can also report a native session reference. `pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_session": {
|
||||
"source": "herdr:codex",
|
||||
"agent": "codex",
|
||||
"kind": "id",
|
||||
"value": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If no native session reference is stored, the field is omitted.
|
||||
|
||||
`pane.get`, `pane.list`, `agent.get`, and `agent.list` also expose `foreground_cwd` when Herdr can resolve the cwd of the process currently controlling the pane PTY. The existing `cwd` field remains the pane/workspace cwd used for labels, follow-cwd behavior, and restored session state.
|
||||
|
||||
Use `pane.report_metadata` when a user hook wants to customize presentation without taking over lifecycle state from a Herdr integration.
|
||||
|
||||
```json
|
||||
|
|
|
|||
Loading…
Reference in New Issue