docs/maintainer/ty.rst

ty: sending automated contributor feedback
==========================================
B4 makes it easier to send automated developer feedback when you apply
patches or pull requests to your git tree.

Tracking retrieved patches and PRs
----------------------------------
Any patches or pull requests you retrieve with ``b4 am,shazam,pr`` will
be automatically tracked by b4 in your homedir (usually, in
``$HOME/.local/share/b4``, but may vary if your ``$XDG_DATA_HOME`` is
set to a different value). There are four kinds of files in that
directory:

* .am: contain information about patches retrieved with ``b4 am`` or
  ``b4 shazam``
* .pr: contain information about pull requests retrieved with ``b4 pr``
* .sent: either .am or .pr tracked files that were successfully sent
  using ``b4 ty``
* .discarded: either .am or .pr tracked files that were deleted using
  ``b4 ty``

All of these files contain JSON data about the series or pull requests
being tracked.

Using the Auto-Thankanator
--------------------------
If you've retrieved and applied some patches to your tree, you should be
able to fire up the "auto-thankanator", which uses patch-id and commit
subject tracking to figure out which series from those you have
retrieved were applied to your tree. The process is usually pretty
fast and fairly accurate.

Manually listing and thanking
-----------------------------
If you don't want to use the auto-thankanator, or if it's not finding a
patch series (e.g. because you've made changes to a commit before
applying it to your tree), you can use a more manual process. First,
list all tracked series::

    $ b4 ty -l

Identify the series that you're sure got applied, then generate the
thank-you message::

    $ b4 ty -t 1

This will write out a .thanks file in the current directory, which you
can then modify and send out.

Sending out mail vs. writing .thanks files
------------------------------------------
By default, ``b4 ty`` will write out .thanks files in the current
directory, which allows you to edit the body of the message before
sending it out, e.g. using ``mutt``::

    $ mutt -f foo.thanks

However, if you have a configured ``sendemail`` section, you can also
tell b4 to send out the thanks message directly::

    $ b4 ty -aS --dry-run

The above command will locate all tracked series that got applied to
your tree and show the messages that are going to be sent out. If you're
happy with the results, you can omit the ``--dry-run`` switch to
actually send the mail.

Editing the templates
---------------------
You can edit the default templates that are provided with b4 to
customize the thank-you message. Once you have your own versions, you
can specify the path to the template to use via the
``b4.thanks_am_template`` and ``b4.thanks_pr_template`` configuration
parameters. See :ref:`ty_settings` for details.

Optional flags
--------------
``-g GITDIR, --gitdir GITDIR``
  The git tree to use instead of the current working directory.

``-o OUTDIR, --outdir OUTDIR``
  Where to write the .thanks files if not into the current directory.
  Has no effect when ``-S`` is used.

``-l, --list``
  Lists all tracked patch series and pull requests.

``-t THANKFOR, --thank-for THANKFOR``
  From the listing generated by ``--list``, specify which thank-you
  notes should be sent. This command accepts comma-separated values and
  ranges, including open-ended ranges, e.g.: ``-t 1,3,5-7,9-``. It also
  accepts ``all``.

``-d DISCARD, --discard DISCARD``
  From the listing generated by ``--list``, specify which thank-you
  notes should be discarded. This command accepts comma-separated values
  and ranges, including open-ended ranges, e.g.: ``-t 1,3,5-7,9-``. It
  also accepts ``all``.

``-a, --auto``
  The auto-thankanator: uses patch-id and commit subject matching to
  figure out which tracked series or pull request have been applied to
  your tree.

``-b BRANCH, --branch BRANCH``
  When using ``--auto``, specify which git branch should be used if not
  the currently active branch.

``--since SINCE``
  When using ``--auto``, this lets you adjust how far back b4 will look
  to find your own commits. Takes the same format as ``--since`` flags
  passed to git, with the default of ``1.week``.

``-S, --send-email``
  Instead of writing .thanks files, send the email directly. Requires
  that the ``sendemail`` section is present in your git configuration.

``--dry-run``
  When used with ``-S``, will not actually send email, just print them
  out to stdout.

``--pw-set-state PW_SET_STATE``
  When patchwork integration is configured, sets the specified patchwork
  state instead of the default specified in config settings (use with
  -a, -t or -d). See :ref:`patchwork_settings` for more details.