doc: document prep --check

Initial documentation for prep --check.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

4 files changed, 179 insertions, 127 deletions

diff --git a/.vale.ini b/.vale.ini
index 4113671..47fb99f 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -1,6 +1,7 @@
 StylesPath = ~/.local/share/vale/styles
 MinAlertLevel = suggestion
 Packages = Google, proselint, Readability
+Vocab = git
 
 [*.rst]
 BasedOnStyles = Vale, Google, proselint, Readability
diff --git a/docs/contributor/overview.rst b/docs/contributor/overview.rst
index bacc5fa..c2045e0 100644
--- a/docs/contributor/overview.rst
+++ b/docs/contributor/overview.rst
@@ -22,15 +22,15 @@ easier for contributors to submit patch series:
 
   This is a fairly new set of features and can still be buggy or do
   something unexpected. While a lot of work has gone into making sure
-  that your git tree is not harmed in any way, it is best to have
-  backups and to always check things with ``--dry-run`` when that option
-  is available.
+  that your git tree isn't harmed in any way, it's best to have backups
+  and to always review things with ``--dry-run`` when that option is
+  available.
 
   If you come across a bug or unexpected behaviour, please report the
   problem to the Tools mailing list.
 
-Do I still need to be able to send email?
------------------------------------------
+Is it still required to be able to send email?
+----------------------------------------------
 While ``b4 send`` makes it possible to submit patches without having
 access to an SMTP server, you still need a reasonable mail server for
 participating in conversations and code review.
@@ -40,10 +40,10 @@ care if your mail server performs some kind of content mangling that
 causes patches to become corrupted, or if it doesn't provide a way to
 send mail via SMTP.
 
-What is the b4 contributor workflow?
-------------------------------------
-The workflow is very much git-oriented, so you should expect to need to
-know a lot about such git commands like ``git commit --amend`` and ``git rebase
+What's the b4 contributor workflow?
+-----------------------------------
+You can expect to be working with git commits, so you should be familiar
+with such git commands as ``git commit --amend`` and ``git rebase
 -i``. In general, the process goes like this:
 
 1. Prepare your patch series by using ``b4 prep`` and queueing your
@@ -56,29 +56,32 @@ know a lot about such git commands like ``git commit --amend`` and ``git rebase
 
 3. When you are almost ready to send, use ``b4 prep --auto-to-cc``
    to collect the relevant addresses from your commits. If your project
-   uses a ``MAINTAINERS`` file, this will also perform the required
-   query to figure out who should be included on your patch series
-   submission.
+   uses a ``MAINTAINERS`` file, this should also perform the required
+   query to figure out whom to include on your patch series submission.
 
-4. Review the list of addresses that were added to the cover letter and,
+4. Review the list of addresses that b4 added to the cover letter and,
    if you know what you're doing, remove any that you think are
    unnecessary.
 
-5. Send your series using ``b4 send``. This will automatically reroll
-   your series to the next version and add changelog entries to the
-   cover letter.
+5. Run pre-flight checks on your series to improve your chances of
+   getting positive reviews.
 
-6. Await code review and feedback from maintainers.
+6. Send your series using ``b4 send``. This should automatically
+   increment your series to the next version and add changelog entries
+   to the cover letter.
 
-7. Apply any received code-review trailers using ``b4 trailers -u``.
+7. Await code review and feedback from maintainers.
 
-8. Use ``git rebase -i`` to make any changes to the code based on the
+8. Apply any received code-review trailers using ``b4 trailers -u``.
+
+9. Use ``git rebase -i`` to make any changes to the code based on the
    feedback you receive. Remember to record these changes in the cover
    letter's changelog.
 
-9. Unless series is accepted upstream, GOTO 3.
+10. Unless maintainers accept your series and merge them upstream, go
+    back to #2 and continue until you succeed.
 
-10. Clean up obsolete prep-managed branches using ``b4 prep --cleanup``
+11. Clean up obsolete prep-managed branches using ``b4 prep --cleanup``
 
 Please read the rest of these docs for details on the ``prep``,
-``send``, and ``trailers`` subcommands.
+``send``, and ``trailers`` commands.
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 8215196..d0c7275 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -7,6 +7,7 @@ for submission upstream. It generally consists of the following stages:
 2. add commits as usual and work with them using ``git rebase -i``
 3. prepare the cover letter using ``b4 prep --edit-cover``
 4. prepare the list of recipients using ``b4 prep --auto-to-cc``
+5. run basic checks using ``b4 prep --check``
 
 Starting a new topical branch
 -----------------------------
@@ -15,38 +16,38 @@ is to create a topical branch::
 
     b4 prep -n descriptive-name [-f tagname]
 
-It is important to give your branch a short descriptive name, because it
-will become part of the unique ``change-id`` that will be used to track
-your proposal across revisions. In other words, don't call it "stuff" or
+It's important to give your branch a short descriptive name, because it
+becomes part of the unique ``change-id`` that is used to track your
+proposal across revisions. In other words, don't call it "stuff" or
 "foo".
 
-This command will do the following:
+This command performs the following operations:
 
-1. Create a new branch called ``b4/descriptive-name`` and switch to it.
-2. Create an empty commit with a cover letter template.
+1. Creates a new branch called ``b4/descriptive-name`` and switches to it.
+2. Creates an empty commit with a cover letter template.
 
 .. note::
 
-   Generally, you will want to fork from some known point in the
-   history, not from some random HEAD commit. You can use ``-f`` to
-   specify a fork-point for b4 to use, such as a recent tag name.
+   Generally, you should fork from some well-defined point in the
+   project history, not from some random tip commit. You can use ``-f``
+   to specify a fork-point for b4 to use, such as a recent tag name.
 
 You can then edit the cover letter using::
 
     b4 prep --edit-cover
 
-This will fire up a text editor using your defined ``$EDITOR`` or
+This should start a text editor using your defined ``$EDITOR`` or
 ``core.editor`` and automatically update the cover letter commit when
-you are done.
+you save and exit.
 
 .. _prep_cover_strategies:
 
 Cover letter strategies
 ~~~~~~~~~~~~~~~~~~~~~~~
-By default, b4 will keep the cover letter in an empty commit at the
-start of your series. This has the following benefits:
+By default, b4 keeps the cover letter in an empty commit at the start of
+your series. This has the following benefits:
 
-* it is easy to keep track where your series starts without needing to
+* it's easy to keep track where your series starts without needing to
   keep a "tracking base branch" around
 * you can view and edit the cover letter using regular git commands
   (``git log``, ``git rebase -i``)
@@ -63,48 +64,49 @@ disadvantages in some less-common situations:
   branch
 
 For this reason, b4 supports alternative strategies for storing the
-cover letter, which can be set using the ``b4.prep-cover-strategy``
-configuration variable.
+cover letter. You can tell ``b4`` which strategy to use using the
+``b4.prep-cover-strategy`` configuration variable.
 
 ``commit`` strategy (default)
   This is the default strategy that keeps the cover letter and all
   tracking information in an empty commit at the start of your series.
-  See above for upsides and downsides.
+  See the preceding section for upsides and downsides.
 
-  This strategy is recommended for developers who mostly send out patch
-  series and do not handle actual subsystem tree management (merging
-  submissions from sub-maintainers, cherry-picking, etc).
+  This is the recommended strategy for developers who mostly send out
+  patch series and don't perform actual subsystem tree management tasks,
+  such as merging submissions from sub-maintainers, cherry-picking
+  commits, etc.
 
 ``branch-description`` strategy
   This keeps the cover letter and all tracking information outside of
-  the git commits by using the branch description configuration value
-  (stored locally in ``.git/config``).
+  the git commits by using the branch description configuration value,
+  stored locally in ``.git/config``.
 
   Upsides:
 
-  * this is how git expects you to handle cover letters (see
-    ``git format-patch --cover-from-description``)
-  * editing the cover letter does not rewrite commit history
+  * this is how git expects you to handle cover letters, see
+    ``git format-patch --cover-from-description``
+  * editing the cover letter doesn't rewrite commit history
   * merging between branches is easiest
 
   Downsides:
 
-  * the cover letter cannot be pushed to a remote and only exists local
-    to your tree
+  * the cover letter only exists local to your tree -- you won't be
+    able to commit it to the repository and push it remotely
   * you have to rely on the base branch for keeping track of where your
     series starts
 
 ``tip-commit`` strategy
   This is similar to the default ``commit`` strategy, but instead of
   keeping the cover letter and all tracking information in an empty
-  commit at the start of your series, it keeps it at the end ("tip") of
-  your series.
+  commit at the start of your series, it keeps it at the tip of your
+  series.
 
   Upsides:
 
   * allows you to push the series to a remote and pull it from a
     different location to continue working on a series
-  * editing the cover letter does not rewrite commit history, which may
+  * editing the cover letter doesn't rewrite commit history, which may
     be easier when working in teams
 
   Downsides:
@@ -116,7 +118,7 @@ configuration variable.
 
 .. note::
 
-   At this time, you cannot easily switch from one strategy to the other
+   At this time, you can't easily switch from one strategy to the other
    once you have created the branch with ``b4 prep -n``. This may be
    supported in the future.
 
@@ -143,62 +145,65 @@ e.g.::
 
     b4 prep -n my-topical-branch -F some-msgid@localhost
 
-If the series was submitted using ``b4 send`` it will even contain all
-the preserved tracking information, but it's not a requirement and
-should work reasonably well with most patch series.
+If you sent the series using ``b4 send`` it should even contain all the
+preserved tracking information, but it works reasonably well with any
+patch series.
 
 Working with commits
 --------------------
 All your commits in a prep-tracked branch are just regular git commits
 and you can work with them using any regular git tooling:
 
-* you can rebase them on a different (or an updated) branch using ``git
-  rebase``
-* you can amend (reword, split, squash, etc) commits interactively using
-  ``git rebase -i``; there are many excellent tutorials available online
-  on how to use interactive rebase
+* you can rebase them using ``git rebase``
+* you can amend, reword, split, squash commits interactively using ``git
+  rebase -i``; there are many excellent tutorials available online on
+  how to use interactive rebase
 
-Unless you are using a very old version of git, your empty cover letter
-commit should be preserved through all rebase operations.
+Unless you are using an old version of git, your empty cover letter
+commit should remain preserved through all rebase operations.
 
 .. note::
 
    You can edit the cover letter using regular git operations, though it
-   is not recommended (best to do it with ``b4 prep --edit-cover``). If
-   you do want to edit it directly using ``git rebase -i``, remember to
-   use ``git commit --allow-empty`` to commit it back into the tree.
-
-What if I only have a single patch?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When you only have a single patch, the contents of the cover letter will
-be mixed into the "under-the-cut" portion of the patch. You can just use
-the cover letter for extra To/Cc trailers and changelog entries as your
-patch goes through revisions. If you add more commits in the future
-version, you can fill in the cover letter content with additional
-information about the intent of your entire series.
+   isn't recommended and it's best to always do it with ``b4 prep
+   --edit-cover``. If you do want to edit it directly using ``git rebase
+   -i``, remember to use ``git commit --allow-empty`` to commit it back
+   into the tree.
+
+What if the series only has a single patch?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When you only have a single patch, b4 should "mix-in" the contents of
+the cover letter into the "under-the-cut" portion of the patch itself,
+where it serves as a source of additional information for the reviewers,
+but never makes it into the actual commit.
+
+You can just use the cover letter for extra To/Cc trailers and changelog
+entries as your patch goes through revisions. If you add more commits at
+some point in the future, you can fill in the cover letter content with
+additional information about the intent of your entire series.
 
 .. _prep_recipients:
 
 Prepare the list of recipients
 ------------------------------
 When you are getting ready to submit your work, you need to figure out
-who the recipients of your series should be. By default, b4 will send
-the series to any address mentioned in the trailers (and to any other
-addresses you tell it to use).
+who the recipients of your series should be. By default, b4 should send
+the series to any address mentioned in the trailers, plus to any other
+addresses you tell it to use.
 
 For the Linux kernel, a required step is to gather the recipients from
-the output of ``get_maintainer.pl``, which b4 will do for you
-automatically when you run the ``auto-to-cc`` command::
+the output of ``get_maintainer.pl``, which b4 does for you automatically
+when you run the ``auto-to-cc`` command::
 
     b4 prep --auto-to-cc
 
-The recipients will be added to the cover letter as extra ``To:`` and
-``Cc:`` trailers. It is normal for this list to be very large if your
-change is touching a lot of files. You can add or remove recipients by
-adding or removing the recipient trailers from the cover letter using
-``b4 prep --edit-cover``.
+B4 should append any discovered recipients to the cover letter as extra
+``To:`` and ``Cc:`` trailers. It's normal for this list to be pretty
+large if your change is touching a lot of files. You can add or remove
+recipients by adding or removing the recipient trailers from the cover
+letter using ``b4 prep --edit-cover``.
 
-For projects that are not using the MAINTAINERS file, there is usually a
+For projects that aren't using the MAINTAINERS file, there is usually a
 single list where you should send your changes. You can set that in the
 repository's ``.git/config`` file as follows::
 
@@ -208,50 +213,88 @@ repository's ``.git/config`` file as follows::
 This may also be already set by the project, if they have a
 ``.b4-config`` file in the root of their git repository.
 
+.. _prep_check:
+
+Checking your work
+------------------
+.. note::
+
+   This is a new feature in version 0.14 and you should consider it
+   experimental.
+
+Once you are getting close to submitting your series, you should run
+``b4 prep --check``. This should run a suite of recommended local checks
+to make sure that your patches do not have some of the more common
+problems, such as spelling errors, missing Signed-off-by trailers, etc.
+
+For the Linux kernel, this automatically runs ``scripts/checkpatch.pl``,
+while other projects may define their own checks as part of the default
+``.b4-config``.
+
 .. _prep_cleanup:
 
 Cleaning up old work
 --------------------
-
-Once your series is accepted upstream, you can archive and clean up the
-prep-managed branch and all its sent tags::
+Once project maintainers accept your series, you can archive and clean
+up the prep-managed branch, together with all of its sent tags::
 
     b4 prep --cleanup
 
-This will list all prep-managed branches in your repository. Pick a
-branch to clean up (make sure it's not currently checked out), and run
+This command lists all prep-managed branches in your repository. Pick a
+branch to clean up, make sure it's not currently checked out, and run
 the command again::
 
     b4 prep --cleanup b4/my-topical-branch
 
-After you confirm your action, this will create a tarball with all the
-patches, cover letters, and tracking information from your series, after
-which the branch and related tags will be deleted from your local
+After you confirm your action, this should create a tarball with all the
+patches, cover letters, and tracking information from your series.
+Afterwards, b4 deletes the branch and all related tags from your local
 repository.
 
 .. _prep_flags:
 
 Prep command flags
 ------------------
-Please also see :ref:`contributor_settings`, which allow setting
-or modifying defaults for some of these flags.
+Please also see :ref:`contributor_settings`, which allows setting or
+modifying defaults for some of these flags.
 
 ``-c, --auto-to-cc``
   Automatically populate the cover letter with addresses collected from
-  commit trailers. If a ``MAINTAINERS`` file is found, together with
-  ``scripts/get_maintainer.pl``, b4 will automatically perform the query
-  to collect the maintainers and lists that should be notified of the
-  change.
+  commit trailers. If b4 finds a ``MAINTAINERS`` file, together with
+  ``scripts/get_maintainer.pl``, it runs the recommended query to
+  collect the maintainers and mailing lists where to send your series.
 
 ``-p OUTPUT_DIR, --format-patch OUTPUT_DIR``
-  This will output your tracked series as patches similar to what
+  This outputs your tracked series as patches similar to what
   ``git-format-patch`` would do.
 
 ``--edit-cover``
-  Lets you edit the cover letter using whatever editor is defined in
-  git-config for ``core.editor``, ``$EDITOR`` if that is not found, or
-  ``vim`` because we're pretty sure that if you don't like vim, you
-  would have already set your ``$EDITOR`` to not be vim.
+  Lets you edit the cover letter using the editor command defined in
+  git-config as ``core.editor``, the ``$EDITOR`` environment var if that
+  isn't found, or ``vim`` -- because it's safe to assume that if you
+  don't like vim, you would have already set your ``$EDITOR`` to use
+  some other command.
+
+``--check`` **(v0.14+)**
+  Runs a set of checks on your series to identify some of the more
+  common problems.
+
+  For the Linux kernel, this runs the following command for each of your
+  commits:
+
+  ``./scripts/checkpatch.pl --terse --no-summary --mailback --showfile``
+
+  You can specify your own command by setting the
+  ``b4.prep-perpatch-check-cmd`` configuration parameter. For example
+  you can make it more strict::
+
+      [b4]
+      prep-perpatch-check-cmd = ./scripts/checkpatch.pl --terse --no-summary --mailback --strict --showfile
+
+  If you want to see a more detailed checkpatch report, you can always
+  run it separately::
+
+      ./scripts/checkpatch.pl --strict --git $(b4 prep --show-info series-range)
 
 ``--show-revision``
   Shows the current series revision.
@@ -268,36 +311,37 @@ or modifying defaults for some of these flags.
   changelogs.
 
 ``--manual-reroll MSGID``
-  Normally, your patch series will be automatically rerolled to the next
-  version after a successful ``b4 send`` (see :doc:`send`). However, if
-  you sent it in using some other mechanism, such as ``git-send-email``,
-  you can trigger a manual reroll using this command. It requires a
-  message-id that can be retrieved from the public-inbox server, so we
-  can properly add the reference to the previously sent series to the
-  cover letter changelog.
+  Normally, your patch series should be automatically rerolled to the
+  next version after a successful ``b4 send`` operation (see
+  :doc:`send`).  However, if you sent it in using some other mechanism,
+  such as ``git-send-email``, you can trigger a manual version reroll
+  using this command. It requires a message-id that can be retrieved
+  from the public-inbox server, so we can properly add the reference to
+  the previously sent series to the cover letter changelog.
 
 ``--set-prefixes PREFIX [PREFIX ...]`` **(v0.11+)**
   If you want to mark your patch as ``RFC``, ``WIP``, or add any other
   subsystem identifiers, you can define them via this command. Do
-  **not** add ``PATCH`` or ``v1`` here, as these will already be
-  automatically added to the subject lines. To remove any extra
-  prefixes you previously set, you can run ``--set-prefixes ''``.
+  **not** add ``PATCH`` or ``v1`` here, as these are already
+  automatically added to the subject lines. To remove any extra prefixes
+  you previously set, you can run ``--set-prefixes ''``.
 
   Alternatively, you can add any extra prefixes to the cover letter
   subject line, using the usual square brackets notation, e.g.::
 
       [RFC] Cover letter subject
 
-  When b4 sends the message, it will be expanded with the usual
-  ``PATCH``, ``vN``, etc.
+  When b4 sends the message, it should add ``PATCH``, ``vN``, to the
+  subject as necessary.
 
 ``--show-info [PARAM]`` **(v0.13+)**
-  Dumps information about the current series that can be parsed by other
-  tools. Starting with v0.13, he parameter can be one of the following:
+  Dumps information about the current series in a format suitable for
+  parsing by other tools. Starting with v0.13, the parameter can be one
+  of the following:
 
-  - **keyname** to show just a specific value from the current branch
-  - **branchname** to show all info about a specific branch
-  - **branchname:keyname** to show a specific value from a specific
+  - **key name** to show just a specific value from the current branch
+  - **branch name** to show all info about a specific branch
+  - **branch name:key name** to show a specific value from a specific
     branch
 
   For example, if you have a branch called ``b4/foodrv-bar`` and you
@@ -319,7 +363,7 @@ or modifying defaults for some of these flags.
 
 ``--cleanup [BRANCHNAME]`` **(v0.13+)**
   Archive and delete obsolete prep-managed branches and all git objects
-  related to them (such as sent tags). Run without parameters to list
+  related to them, such as sent tags. Run without parameters to list
   all known prep-managed branches in the repository. Rerun with the
   branch name to create an archival tarball with all patches, covers,
   and tracking information, and then delete all git objects related to
@@ -334,8 +378,8 @@ or modifying defaults for some of these flags.
 
 ``-F MSGID, --from-thread MSGID``
   After creating a new branch, populate it with patches from this
-  pre-existing patch series. Requires a message-id that can be retrieved
-  from the public-inbox server.
+  pre-existing patch series. Requires a message-id to retrieve from the
+  public-inbox server.
 
 ``-e ENROLL_BASE, --enroll ENROLL_BASE``
   Enrolls your current branch to be b4-prep managed. Requires the name
diff --git a/plan.otl b/plan.otl
index a42b8a3..48c1cfd 100644
--- a/plan.otl
+++ b/plan.otl
@@ -20,8 +20,12 @@ v0.14
 	[X] Refuse to send if checks haven't been run
 	[X] Allow turning off pre-flight check all together, or by individual check
 [_] Document new features
-	[_] How to work with series dependencies
-	[_] How to run pre-flight checks
+	[_] prep --check
+	[_] Series dependencies overview
+	[_] prep --edit-deps
+	[_] prep --check-deps
+	[_] Pre-flight checks overview
+	[_] How to turn off pre-flight checks
 
 v0.15
 -----