docs: rewrite vimdoc and migration notes for implicit refs #394

New issue

Closed

opened 2026-04-25 16:20:54 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-25 16:20:54 +00:00

Part of #389.
Depends on #391, #392, and #393.
Suggested order: 5.

Problem

The current vimdoc and public API docs describe an explicit-number PR model and low-level Lua helpers as the main public surface. That will be wrong or misleading once current-PR commands and high-level Lua entrypoints exist.

Proposed solution

Rewrite the affected docs around the new canonical model.

Key points to document:

:Forge pr, :Forge review, and :Forge pr ci resolve the current PR implicitly
:Forge ci remains current-branch CI history
resolver policy, including no-PR and ambiguous-PR outcomes
preferred top-level Lua entrypoints and their relationship to lower-level helpers
migration notes away from overloaded :Forge pr create behavior and older Lua examples

Scope

doc/forge.nvim.txt
Lua-facing public API examples and docstrings/LuaCATS where needed
migration / compatibility notes

Acceptance criteria

vimdoc clearly distinguishes branch CI from PR checks
the command reference no longer states that all non-create PR actions require an explicit PR number
the documented Lua surface matches the new canonical entrypoints
migration guidance is explicit about renamed/evicted APIs and changed command semantics

Out of scope

removing compatibility shims in code

Part of #389. Depends on #391, #392, and #393. Suggested order: 5. ## Problem The current vimdoc and public API docs describe an explicit-number PR model and low-level Lua helpers as the main public surface. That will be wrong or misleading once current-PR commands and high-level Lua entrypoints exist. ## Proposed solution Rewrite the affected docs around the new canonical model. Key points to document: - `:Forge pr`, `:Forge review`, and `:Forge pr ci` resolve the current PR implicitly - `:Forge ci` remains current-branch CI history - resolver policy, including no-PR and ambiguous-PR outcomes - preferred top-level Lua entrypoints and their relationship to lower-level helpers - migration notes away from overloaded `:Forge pr create` behavior and older Lua examples ## Scope - `doc/forge.nvim.txt` - Lua-facing public API examples and docstrings/LuaCATS where needed - migration / compatibility notes ## Acceptance criteria - vimdoc clearly distinguishes branch CI from PR checks - the command reference no longer states that all non-create PR actions require an explicit PR number - the documented Lua surface matches the new canonical entrypoints - migration guidance is explicit about renamed/evicted APIs and changed command semantics ## Out of scope - removing compatibility shims in code