No OneTemporary
Actions

Size

2 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/userguide/differential_faq.diviner b/src/docs/userguide/differential_faq.diviner
	new file mode 100644
	index 0000000000..5781284a81
	--- /dev/null
	+++ b/src/docs/userguide/differential_faq.diviner
	@@ -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.

File Metadata

Mime Type: text/x-diff
Expires: Jan 19 2025, 20:37 (6 w, 1 d ago)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 1128508
Default Alt Text: (2 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions