mirror of
https://github.com/openai/codex.git
synced 2026-10-27 18:48:37 +00:00
Josh McKinney
1202598434
Publish keymap system documentation first so the implementation stack can be reviewed against explicit behavior and invariants. This commit adds the keymap system guide, action matrix, default keymap template, and config/example documentation updates, plus a rollout plan used to stage the additive refactor and validation work.
70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# TUI Keymap Additive Rollout Plan
|
|
|
|
This plan restructures the existing keymap implementation into a reviewable
|
|
additive stack while preserving the final behavior from revision `0f03e76c`.
|
|
|
|
## Goals
|
|
|
|
- Keep the final behavior effectively identical to `0f03e76c`.
|
|
- Reorder history to show intent and risk reduction clearly.
|
|
- Make each change compile, format cleanly, and pass scoped tests.
|
|
- Establish high-confidence behavior characterization before binding rewrites.
|
|
|
|
## Commit Sequence
|
|
|
|
1. **Docs and specification foundation**
|
|
- Add/reshape long-term docs that explain how the keymap system works.
|
|
- Include:
|
|
- conceptual model
|
|
- action matrix
|
|
- default keymap template guidance with explicit URL
|
|
- testing strategy notes
|
|
- No functional code change.
|
|
|
|
2. **Additive config primitives (not wired)**
|
|
- Introduce keymap config types and schema support in `core`.
|
|
- Keep runtime behavior unchanged by not consuming these config values yet.
|
|
- Ensure parsing/serialization paths are complete and documented.
|
|
|
|
3. **Behavior characterization tests (pre-rewrite)**
|
|
- Add tests that lock down existing event behavior before switching bindings.
|
|
- Cover key event matching and context-sensitive behaviors that must stay stable.
|
|
- Use these tests as the safety net for subsequent rewiring.
|
|
- Run `cargo llvm-cov` and target full branch coverage for keybinding logic.
|
|
|
|
4. **Binding replacement using characterized behavior**
|
|
- Introduce keymap-driven binding resolution and wire call sites.
|
|
- Replace legacy binding checks while preserving characterized behavior.
|
|
- Keep docs in sync with any semantics that became explicit.
|
|
|
|
5. **UX polish and affordances**
|
|
- Apply help/footer/tooltip/key-hint refinements once behavior is stable.
|
|
- Keep affordance text concise and formatted for readability.
|
|
- Update snapshots as needed.
|
|
|
|
## Validation Gates Per Commit
|
|
|
|
For each commit in the sequence:
|
|
|
|
1. Run formatting (`just fmt` in `codex-rs`).
|
|
2. Run scoped tests for affected crates (minimum `cargo test -p codex-tui` for TUI
|
|
changes and relevant `core` tests when `core` changes).
|
|
3. Ensure branch compiles cleanly (`cargo test` path used as compile gate).
|
|
4. For characterization and binding commits, run coverage and track branch
|
|
coverage for keybinding logic (`cargo llvm-cov`).
|
|
|
|
## JJ Workflow
|
|
|
|
- Build stack from `trunk()` with explicit ordered changes.
|
|
- Use `jj new -A` / `jj new -B` to place changes relative to target revisions.
|
|
- Rebase existing implementation changes into the new stack as needed.
|
|
- Resolve conflicts immediately and keep each change coherent.
|
|
- Use clear `jj describe` messages with title + explanatory body.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Final tip behavior matches `0f03e76c` in practice.
|
|
- Stack reads top-to-bottom as: docs -> config -> characterization -> rewiring ->
|
|
UX polish.
|
|
- Each commit is independently reviewable with passing checks.
|