mirror of
https://we.phorge.it/source/phorge.git
synced 2025-01-25 05:58:21 +01:00
821f580c3a
Summary: Try to explain how this stuff works a little better. Let me know what's unclear / missing / not good. Test Plan: Generated documentation, read documentation. Reviewers: btrahan, gschmidt Reviewed By: btrahan CC: aran, epriestley, davidreuss Maniphest Tasks: T904 Differential Revision: https://secure.phabricator.com/D1969
62 lines
2.7 KiB
Text
62 lines
2.7 KiB
Text
@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.
|
|
|
|
= How can I enable syntax highlighting? =
|
|
|
|
You need to install and configure **Pygments**. Consult the configuration file
|
|
for instructions.
|
|
|
|
= What do the whitespace options mean? =
|
|
|
|
Most of these are pretty straightforward, but "Ignore Most" is not:
|
|
|
|
- **Show All**: Show all whitespace.
|
|
- **Ignore Trailing**: Ignore changes which only affect trailing whitespace.
|
|
- **Ignore Most**: Ignore changes which only affect leading or trailing
|
|
whitespace (but not whitespace changes between non-whitespace characters)
|
|
in files which are not marked as having significant whitespace.
|
|
In those files, show whitespace changes. By default, Python (.py) and
|
|
Haskell (.lhs, .hs) are marked as having significant whitespace, but this
|
|
can be changed in the `differential.whitespace-matters` configuration
|
|
setting.
|
|
- **Ignore All**: Ignore all whitespace changes in all files.
|