Re: [PATCH] git-gui: add a readme

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi Pratyush,

On Sat, 5 Oct 2019, Pratyush Yadav wrote:

> It is a good idea to have a readme so people finding the project can
> know more about it, and know how they can get involved.
>
> Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
> ---
>
> I don't have much experience writing this kind of readme or
> documentation, so comments are appreciated. Please feel free to chime in
> with suggestions and things that can also be added.
>
>  README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 128 insertions(+)
>  create mode 100644 README.md
>
> diff --git a/README.md b/README.md
> new file mode 100644
> index 0000000..d76122d
> --- /dev/null
> +++ b/README.md
> @@ -0,0 +1,128 @@
> +# Git Gui - A graphical user interface for Git

Why not Git GUI? "Git" is a name, "GUI" is an abbreviation, and the
convention is (at least as far as I can tell) to upcase abbreviations.

> +
> +Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
> +you to use the git source control management tools via a GUI. This includes
                  ^^^

I prefer to spell it as "Git", i.e. with an upper-case "G" because "Git"
is a name. Lower-case "git" would suggest the command-line executable to
me.

> +staging, commiting, adding, pushing, etc. It can also be used as a blame
> +viewer, a tree browser, and a citool (make exactly one commit before exiting
> +and returning to shell). More details about git-gui can be found in its manual
> +page by either running `man git-gui`, or by visiting the [online manual
> +page](https://git-scm.com/docs/git-gui).
> +
> +Git Gui was initially written by Shawn O. Pearce, and is distributed with the
> +standard git installation.
> +
> +# Building and installing
> +
> +Most of Git Gui is written in Tcl, so there is not much compilation involved.

"Most"? Are there parts that are not written in Tcl?

As far as I can tell, _no_ compilation is involved. Just a couple of
substitutions, e.g. the version number.

> +Still, some things do need to be done, so you do need to "build" it.
> +
> +You can build Git Gui using:
> +
> +```
> +make
> +```
> +
> +And then install it using:
> +
> +```
> +make install
> +```
> +
> +You probably need to have root/admin permissions to install.
> +
> +# Contributing
> +
> +The project is currently maintained by Pratyush Yadav over at
> +https://github.com/prati0100/git-gui. Even though the project is hosted at
> +GitHub, the development does not happen over GitHub Issues and Pull Requests.
> +Instead, an email based workflow is used. The git mailing list
> +[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
> +discussed and reviewed.

You might want to accompany this `README.md` with a
`.github/PULL_REQUEST_TEMPLATE.md` that explains this, and discourages
contributors from opening PRs (mind, some contributors will not even
read this, let alone delete it nor refrain from opening PRs, but most
contributors will read it and avoid unnecessary work).

Ciao,
Johannes

> +
> +More information about the git mailing list and instructions to subscribe can
> +be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
> +
> +## Sending your changes
> +
> +Since the development happens over email, you need to send in your commits in
> +text format. Commits can be converted to emails via the two tools provided by
> +git: `git-send-email` and `git-format-patch`.
> +
> +If you are sending multiple patches, it is recommended to include a cover
> +letter. A cover letter is an email explaining in brief what the series is
> +supposed to do. A cover letter template can be generated by passing
> +`--cover-letter` to `git-format-patch`.
> +
> +After you send your patches, you might get a review suggesting some changes.
> +Make those changes, and re-send your patch(es) in reply to the first patch of
> +your initial version. Also please mention the version of the patch. This can be
> +done by passing `-v X` to `git-format-patch`, where 'X' is the version number
> +of the patch(es).
> +
> +### Using git-send-email
> +
> +You can use `git-send-email` to send patches via email. A pretty good guide to
> +configuring and using `git-send-email` can be found
> +[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
> +
> +### Using your email client
> +
> +If your email client supports sending mbox format emails, you can use
> +`git-format-patch` to get an mbox file for each commit, and then send them. If
> +there is more than one patch in the series, then all patches after the first
> +patch (or the cover letter) need to be sent as replies to the first.
> +`git-send-email` does this by default.
> +
> +### Using GitGitGadget
> +
> +Since some people prefer a GitHub pull request based workflow, they can use
> +[GitGitGadget](https://gitgitgadget.github.io/) to send in patches. The tool
> +was originally written for sending patches to the Git project, but it now also
> +supports sending patches for git-gui.
> +
> +Instructions for using GitGitGadget to send git-gui patches, courtesy of
> +Johannes Schindelin:
> +
> +If you don't already have a fork of the [git/git](https://github.com/git/git)
> +repo, you need to make one. Then clone your fork:
> +
> +```
> +git clone https://github.com/<your-username>/git
> +```
> +
> +Then add GitGitGadget as a remote:
> +
> +```
> +git remote add gitgitgadget https://github.com/gitgitgadget/git
> +```
> +
> +Then fetch the git-gui branch:
> +
> +```
> +git fetch gitgitgadget git-gui/master
> +```
> +
> +Then create a new branch based on git-gui/master:
> +
> +```
> +git checkout -b <your-branch-name> git-gui/master
> +```
> +
> +Make whatever commits you need to, push them to your fork, and then head over
> +to https://github.com/gitgitgadget/git/pulls and open a Pull Request targeting
> +git-gui/master.
> +
> +GitGitGadget will welcome you with a (hopefully) helpful message.
> +
> +## Signing off
> +
> +You need to sign off your commits before sending them to the list. You can do
> +that by passing the `-s` option to `git-commit`. You can also use the "Sign
> +Off" option in Git Gui.
> +
> +A sign-off is a simple 'Signed-off-by: A U Thor \<author@example.com\>' line at
> +the end of the commit message, after your explanation of the commit.
> +
> +A sign-off means that you are legally allowed to send the code, and it serves
> +as a certificate of origin. More information can be found at
> +[developercertificate.org](https://developercertificate.org/).
> --
> 2.21.0
>
>