diff --git a/BETA.md b/BETA.md new file mode 100644 index 0000000..1d21397 --- /dev/null +++ b/BETA.md @@ -0,0 +1,82 @@ +# Beta Testing + +This branch is the v3 beta candidate. Do not tag or publish it as `v3.0.0` +until the checklist below is closed. + +## Install the beta + +Existing checkout: + +```bash +cd ~/.vim +git fetch origin +git checkout release/v3-candidate +git pull --ff-only +vim -Nu ~/.vimrc -n -es +'PlugInstall --sync' +'qa!' +``` + +Fresh checkout: + +```bash +git clone --branch release/v3-candidate https://github.com/m1ngsama/chopsticks.git ~/.vim +ln -sf ~/.vim/.vimrc ~/.vimrc +vim -Nu ~/.vimrc -n -es +'PlugInstall --sync' +'qa!' +``` + +Keep local choices in `${XDG_CONFIG_HOME:-~/.config}/chopsticks.vim`: + +```vim +let g:chopsticks_profile = 'engineer' +let g:chopsticks_keymap_style = 'space' +``` + +## Daily test loop + +Use the beta for real editing, not only demos. For each session, record: + +- The task: project navigation, code edit, grep, git, LSP, Markdown, SSH. +- The first key you tried when you got stuck. +- Whether `SPC ?`, `:ChopsticksTutor`, or `:ChopsticksStatus` answered it. +- Any mapping that felt slow, awkward, surprising, or too easy to mistype. +- Any documentation line that was wrong, missing, or redundant. + +## Workflows to exercise + +```text +SPC SPC find file SPC / grep project +s + 2ch jump on screen gd / gr definition / references +SPC rr run current file SPC gs git status +SPC cf format SPC ca code action +SPC ? active cheat sheet :ChopsticksStatus health +``` + +Also test the boring path: save, quit, reopen Vim, edit over SSH, open a large +file, edit Markdown, and use a machine with missing optional tools. + +## Exit criteria + +- `s` as the default visible jump still feels worth the native override after + real editing. +- No high-frequency action requires remembering an undocumented key. +- README, QUICKSTART, `SPC ?`, and `:ChopsticksTutor` teach the same layout. +- `scripts/test.sh quick` and `scripts/test.sh vim` pass locally. +- The README GIF has been regenerated from `.github/demo.tape` after any public + key change. +- The beta has been tested on macOS and over SSH on Linux. + +## Roll back + +Return to the latest stable release: + +```bash +cd ~/.vim +git fetch origin --tags +git checkout v2.2.0 +vim -Nu ~/.vimrc -n -es +'PlugInstall --sync' +'qa!' +``` + +Or keep the code but switch back to the legacy layout: + +```vim +let g:chopsticks_keymap_style = 'classic' +``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a61ca9..fd9f9ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## 3.0.0-beta.1 — 2026-05-23 ### Breaking diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b104bcc..e976e8c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ 1. **No Node.js in the Vim runtime.** Plugins must work with pure VimScript — no coc.nvim or other Node-backed completion engines. External CLIs (prettier, eslint, markdownlint, stylelint, tsc) installed via npm are fine; ALE shells out to them as optional system tools, not as part of the Vim runtime. 2. **Startup matters.** Run `vim -u .vimrc -i NONE --startuptime /tmp/s.log -es -N -c qa!` before and after. If your change adds >1ms, it needs a good reason. 3. **Works on TTY.** Test over SSH. If it breaks in a terminal without true color, fix it or gate it behind `g:is_tty`. -4. **Native-first keymaps.** Enhance Vim's native behavior instead of replacing it. Do not override built-in motions, operators, text objects, or help-oriented keys for discoverability alone; prefer leader-prefixed or otherwise non-conflicting ergonomic mappings. +4. **Native-first keymaps.** Enhance Vim's native behavior instead of replacing it. Do not override built-in motions, operators, text objects, or help-oriented keys for discoverability alone. Rare exceptions, such as the default Space-layout `s` jump, must have a documented native replacement, cheat-sheet coverage, and a classic-layout fallback. 5. **One module, one concern.** Don't put git config in lsp.vim. ## Adding a plugin @@ -14,7 +14,7 @@ 2. If it's not needed at startup, lazy-load it: `Plug 'foo/bar', { 'on': 'FooCommand' }` 3. Put config in the appropriate module 4. Check new mappings against native Vim behavior before adding them -5. Update the cheat sheet in `modules/tools.vim` if you add keybindings +5. Update the cheat sheet definitions in `modules/cheatsheet.vim` if you add keybindings 6. Run `scripts/test.sh vim` locally after installing plugins 7. Test on both macOS and Linux when changing terminal or package-manager behavior diff --git a/QUICKSTART.md b/QUICKSTART.md index 1162cf8..1a3fc82 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -141,4 +141,5 @@ syntax. Enable the heavier Markdown tools only when you want them. The `SPC ?` cheat sheet follows your active profile, so `minimal` users only see keys for features that are actually loaded. -See [README](README.md) for the full reference. See the [wiki](https://github.com/m1ngsama/chopsticks/wiki) for deep dives. +See [README](README.md) for the full reference. For beta testing and rollback, +see [BETA.md](BETA.md). diff --git a/README.md b/README.md index c47d844..32b8a46 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,9 @@ curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash ``` +This branch is a v3 beta candidate, not a tagged stable release. Use +[BETA.md](BETA.md) when testing the Space keymap before promotion. + --- ## Why @@ -315,7 +318,8 @@ Each module is self-contained. Comment out one line in `.vimrc` to disable it. A | Everything slow | Large file? Auto-disabled >10MB | | What's installed? | `:ChopsticksStatus` shows tools, LSP, linters | -More in the [wiki](https://github.com/m1ngsama/chopsticks/wiki). +For deeper checks, start with `:ChopsticksStatus`, `SPC ?`, +`:ChopsticksTutor`, and [QUICKSTART.md](QUICKSTART.md). ## Contributing diff --git a/modules/cheatsheet.vim b/modules/cheatsheet.vim index 0fd4320..1347d54 100644 --- a/modules/cheatsheet.vim +++ b/modules/cheatsheet.vim @@ -75,7 +75,7 @@ function! s:CheatSheet() abort call extend(l:lines, [ \ ' SPC rr run file', - \ ' SPC cW strip trailing (v)', + \ ' SPC cW strip trailing', \ ' SPC c= re-indent file (opt-in)', \ ' SPC = re-indent (v)', \ ]) @@ -222,7 +222,7 @@ function! s:CheatSheet() abort \ ' Alt+j/k move line (v)', \ ' ,* replace word (v)', \ ' ,F re-indent (v)', - \ ' ,W strip trailing (v)', + \ ' ,W strip trailing', \ '', \ ' ── git ───────────────────', \ ' ,gs status', diff --git a/scripts/test-quick.sh b/scripts/test-quick.sh index 4fa20ab..b4cf906 100755 --- a/scripts/test-quick.sh +++ b/scripts/test-quick.sh @@ -26,7 +26,7 @@ check_shell() { check_docs() { step "Markdown lint" need markdownlint - markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md + markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md BETA.md if command -v vhs >/dev/null 2>&1; then vhs validate .github/demo.tape