1436779 - End-user docs should mention Done auto-submitting and revision formatting tips

Status: NEW

(Conduit :: Documentation, enhancement, P3)

Description

[Māris Fogels [:mars] (please needinfo)]

The end-user documentation should mention these two parts of the developer workflow so that new Phabricator users don't have to discover them themselves.

1.  If you use Linux kernel-ish commit message formatting, you should use "arc diff --edit" to update your revision details and summary.

Many projects use git-commit-style message formatting, with 70 character limits to line length and such.  However, the Phabricator UI does not enforce this formatting when editing your revision title or summary.  Because your revision title and summary will eventually be turned into the commit submitted to mainline, you can't rely on the Phabricator UI for anything but trivial edits.

To get around this, developers should use the 'arc diff --edit' command to update their revision summaries.  'arc diff --edit' opens a vim editor by default, and users can configure their editor to enforce the commit message guidelines.

2.  Phabricator auto-submits all review comments marked as "Done" when you push a new diff with "arc diff".

The auto-submitting of Done comments makes the fixup-commit workflow easier.  Developers can got from comment to comment in the review feedback, submit a fixup commit for each comment.  When they submit a fixup commit on their local system, the developer checks the "Done" box (keep your fixup commit message very short, preferably just a few words).  When all fixup commits are ready to go, the developer can run "arc diff" without coming back to the Phabricator UI.  The revision comments marked as "Done" will automatically be submitted, and they will be grouped with a nice summary message, too.