mirror of
https://we.phorge.it/source/phorge.git
synced 2024-12-25 06:50:55 +01:00
Document why "accept" is sticky
Summary: This is a fairly common question but I think it's the right product behavior, document it so I can reference the docs next time it comes up. Test Plan: Generated and read documentation. Reviewers: btrahan, jungejason Reviewed By: jungejason CC: aran, jungejason Maniphest Tasks: T735 Differential Revision: https://secure.phabricator.com/D1310
This commit is contained in:
parent
468d2eaa10
commit
c289ec304a
1 changed files with 42 additions and 0 deletions
42
src/docs/userguide/differential_faq.diviner
Normal file
42
src/docs/userguide/differential_faq.diviner
Normal file
|
@ -0,0 +1,42 @@
|
||||||
|
@title Differential User Guide: FAQ
|
||||||
|
@group userguide
|
||||||
|
|
||||||
|
Common questions about Differential.
|
||||||
|
|
||||||
|
= Why does an "accepted" revision remain accepted when it is updated? =
|
||||||
|
|
||||||
|
When a revision author updates an "accepted" revision in Differential, the
|
||||||
|
state remains "accepted". This can be confusing if you expect the revision to
|
||||||
|
change to "needs review" when it is updated.
|
||||||
|
|
||||||
|
This behavior is intentional, to encourage authors to update revisions when they
|
||||||
|
make minor changes after a revision is accepted. For example, a reviewer may
|
||||||
|
accept a change with a comment like this:
|
||||||
|
|
||||||
|
Looks great, but can you add some documentation for the foo() function
|
||||||
|
before you land it? I also caught a couple typos, see inlines.
|
||||||
|
|
||||||
|
If updating the revision reverted the status to "needs review", the author
|
||||||
|
is discouraged from updating the revision when they make minor changes because
|
||||||
|
they'll have to wait for their reviewer to have a chance to look at it again.
|
||||||
|
|
||||||
|
Instead, the "accept" state is sticky to encourage them to update the revision
|
||||||
|
with a comment like:
|
||||||
|
|
||||||
|
```- Added docs.
|
||||||
|
- Fixed typos.```
|
||||||
|
|
||||||
|
This makes it much easier for the reviewer to go double-check those changes
|
||||||
|
later if they want, and the update tells them that the author acknowledged their
|
||||||
|
suggestions even if they don't bother to go double-check them.
|
||||||
|
|
||||||
|
If an author makes significant changes and wants to get them looked at, they can
|
||||||
|
always "request review" of an accepted revision, with a comment like:
|
||||||
|
|
||||||
|
When I was testing my typo fix, I realized I actually had a bug, so I had to
|
||||||
|
make some more changes to the bar() implementation -- can you look them over?
|
||||||
|
|
||||||
|
If authors are being jerks about this (making sweeping changes as soon as they
|
||||||
|
get an accept), solve the problem socially by telling them to stop being jerks.
|
||||||
|
Unless you've configured additional layers of enforcement, there's nothing
|
||||||
|
stopping them from silently changing the code before pushing it, anyway.
|
Loading…
Reference in a new issue