== Introduction ==

Different people have different preferences as for which tools they like to
use.

For instance, to send mails, some people like to use the command like, other
like to use web interfaces, other like to use graphical mail clients, etc.
It's good to have so many choices as it empower people to adapt technology
to them instead of having to adapt to a single way of doing things, which
cannot even work for everybody or every use case.

For the review of patches, different people also have different preferences.
Some people like to use git to download the patches and then review them on
their local computer, other like to review them in a mail client, and other
like to review them on a web interface. What is more practical for a given
person can also change on the characteristics of patches like its size.

While this script is made for people that like to send patches from the
command line, it helps them generate mails that makes it easy for
reviewers to use the tool of their choices to review patches.

This way, when reviewers will read the patch serie, along with the patches,
there will also be an URL to clone the patches, an URL to a web interface
to view the patches, and a friendly message to make it more human.

The text is expected to be copy-pasted as it empower users using this tool to
easily change the text, and spot bugs if there are any. Both would not be
possible if the tool was fully automatic.

== Configuration ==
First copy the example configuration file in the configuration directory:
  $ cp replicant_prepare_patch.conf ~/.config/replicant/

Then modify the content of ~/.config/replicant/replicant_prepare_patch.conf
to suit your needs.

The configuration file path also follows the XDG Base Directory Specification
which is available here:
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

== Usage ==
This tool expect you to setup a git remote that points to the repository
you want to contribute to, in your namespace on the Replicant git server.

For example I use GNUtoo as remote for the GNUtoo namespace:
  $ git remote get-url GNUtoo
  ssh://git@git.replicant.us/GNUtoo/vendor_replicant-scripts.git

Unfortunately, at this time it's not possible to configure the name of
that namespace for each individual repositories, as the code assume that
it is always the same.

Users using this script are expected to manually push the patch serie in
the remote git repository, in any branch or tag they wish.

This tool can then figure out where to find all the information it needs
thanks to the git_remote setting that points to the name of the remote.
As the git hash are used, it doesn't need to know in which branch or tags the
code is pushed.

Once everything is pushed, you can then use the script to generate the example
mail text and the commands to send the mails. As we want to send only one patch
starting from the current HEAD we can use this command:
  $ ./replicant_prepare_patch.py HEAD 1
  patches:
  --------
  0001-Add-script-to-prepare-patches.patch

  git command:
  ------------
  git send-email --compose --to=replicant@osuosl.org 0001-Add-script-to-prepare-patches.patch

  Cover mail:
  -----------
  Hi,

  In addition to the patch that will follow in a response to
  this mail, here's an URL to the see the patch in a web interface:
  https://git.replicant.us/contrib/GNUtoo/vendor_replicant-scripts/commit/?id=5b6757fc6c6f852a4176bb7fc8f32e05c21f703f

  And here's how to get it in a git repository:
  git clone https://git.replicant.us/GNUtoo/vendor_replicant-scripts
  cd vendor_replicant-scripts
  git show 5b6757fc6c6f852a4176bb7fc8f32e05c21f703f

  Denis.

We can then use the git command which will prompt you to write an email to
introduce the patch serie, where you can paste and potentially modify the cover
mail.