Appearance
Proposals and review
Review, built for what this product is: pages, not branches.
A proposal is a whole suggested version of a page, itemised into one decision per block. A reviewer can turn any of them down and take the rest.
Who proposes, who decides
- Proposing is what
commentaccess can do instead of editing. That level used to mean "may leave a comment"; it now also means "may suggest a change, and let somebody who can edit decide". The three access levels already described a review — this makes the model say so. - Deciding requires
writeon the page the proposal changes. There is deliberately no separate "may review" capability: accepting a proposal is an edit, and asking a second permission system about it would be two answers to one question.
What a proposal is, and is not
A snapshot, not a lock. The page stays editable while a proposal waits. If it changes underneath one, the reviewer is told what has been written since, and the proposal stays open — a conflict is a question for a person, not a merge to resolve automatically.
The base comes from the server's own log, never from the client. A proposal can therefore never claim the page said something it did not.
Selection is implemented as start from the proposal and undo the refusals, rather than the other way round — so the common case, accepting all of it, is the proposal exactly, with nothing reassembled.
Who hears about it
A proposal reaches the inbox of everybody watching the page. When nobody is watching, it reaches the people who wrote the page's content, less anybody who has asked not to be told — so a suggestion on an old page is never left for nobody. Whoever proposed it hears the decision.
Proposals that come from a Markdown page
On a page written as Markdown, proposals also arise by themselves: an edit that meets somebody else's change to the same block — two people in one block at once, or writing done offline while somebody changed it — is filed as a proposal rather than written over them, so a person decides.
Attribution
Applied edits are attributed to the reviewer, at the moment they accepted them. The person who pressed Apply is the person who put those words on the page. The proposal itself records who suggested it, so credit is not lost — it is just not backdated onto somebody who never edited the page.
From an external file
pnpm merge:git --propose sends an externally edited Markdown file for review instead of writing it into the page. That is the right shape when the person editing the file and the person who owns the page are different people. See merging changes back.
Known limits
- A reviewer cannot edit a proposal. Changing somebody else's suggestion and then accepting it is a different act, and it would arrive wearing their name.
- No conversation on a proposal. Comments anchor to blocks on a page; a proposal's blocks are not on one yet. Discussion belongs in comments on the page.