Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools

From: Matthieu Moy <matthieu.moy@univ-lyon1.fr>
Date: Apr 16, 2022, 13:25 UTC
Message-ID: <0f8dbbd6-4d7b-4530-ec85-2eddfcdc9825@univ-lyon1.fr>
In-Reply-To: <63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr>

On 4/16/22 14:34, COGONI Guillaume wrote:

> This document aims to gather tools that have a README and/or scripts in
> the GIT project

We usually spell the project name as Git, and the command name as git. And nothing as GIT ;-).

Show 7 quoted lines

> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)
>   TECH_DOCS += MyFirstContribution
>   TECH_DOCS += MyFirstObjectWalk
>   TECH_DOCS += SubmittingPatches
>  +TECH_DOCS += ToolsOnGit

If the goal is to document tools that can be used to develop Git itself, probably ToolsForGit would be more appropriate...

Show 5 quoted lines

> --- /dev/null
> +++ b/Documentation/ToolsOnGit.txt
> @@ -0,0 +1,35 @@
> +Tools on GIT
> +============

... and "Tools for developing Git" a better long title?

> +== Summary
> +
> +This document aims to gather tools that have a README and/or scripts in > +the GIT project.

I don't think having a README should be the criterion here. To me the criterion should be "tools that may not work out of the box, but for which some explanation, configuration or script allow using the tool properly".

Show 20 quoted lines

> +[[author]]
> +=== Author
> +
> +The Git community.
> +
> +[[table_of_contents]]
> +== Table of contents
> +
> +- <<vscode>>
> +- <<emacs>>
> +
> +[[vscode]]
> +=== Visual Studio Code (VS Code)
> +
> +The contrib/vscode/init.sh script creates configuration files that enable
> +several valuable VS Code features. See contrib/vscode/README.md for more
> +information on using the script.
> +
> +In particular, this script enables using the VS Code visual debugger, including
> +setting breakpoints, logpoints, conditional breakpoints and more in the editor.

I don't think the last sentence is needed, and if it is, it would be better within contrib/vscode/README.md (so that someone reaching this README directly do see the information too).

> +[[emacs]]
> +=== Emacs
> +
> +See contrib/emacs/README for more information.

This README starts with "This directory used to contain ..." (note the "used to". There's no reason to point the user to obsolete scripts.

Also, the stuff that used to be in this directory do not fall in the same category. They were targeted at users of both Git and Emacs, but not specifically to develop Git itself.

OTOH, CodingGuidelines's suggestion to configure Emacs like this is IMHO typically something that could appear in this document:

  - For Emacs, it's useful to put the following in
    GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:

     ;; note the first part is useful for C editing, too
     ((nil . ((indent-tabs-mode . t)
                   (tab-width . 8)
                   (fill-column . 80)))
      (cperl-mode . ((cperl-indent-level . 8)
                     (cperl-extra-newline-before-brace . nil)
                     (cperl-merge-trailing-else . t))))

Actually, the Linux kernel's CodingStyle contains more relevant stuff (for C, not Perl):

 
https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it

(But aren't all Git devs former kernel developers? ;-) )

Cheers,

-- 
Matthieu Moy
https://matthieu-moy.fr/