Re: [PATCH v2 1/1] contrib/vscode/: debugging with VS Code and gdb

[Derrick Stolee <derrickstolee@github.com>]

On 4/6/2022 11:18 AM, COGONI Guillaume wrote:
> The externalConsole=true setting is broken for many users (launching the
> debugger with such setting results in VS Code waiting forever without
> actually starting the debugger). Also, this setting is a matter of user
> preference, and is arguably better set in a "launch" section in the
> user-wide settings.json than hardcoded in our script. Remove the line to
> use VS Code's default, or the user's setting.
> 
> Add useful links in contrib/vscode/README.md to help the user to
> configure VS Code and how to use the debugging feature.
> 
> Add a mention to the README and the init.sh in Documentation/
> MyFirstContribution.txt and a part to convince a newcomer that VS Code
> can be helpful.

Sorry for not getting to this in v1.
 
> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
> Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
> Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
> Helped-by: Derrick Stolee <derrickstolee@github.com>

Here, you probably want to flip the order here (Helped-by, then
Co-authored-by, then Signed-off-by). You probably also want the
sign-off of your co-author, too.

The sign-off should be the last thing in the message, because
the previous lines are covered by that sign-off.

> +
> +[[Bonus-useful-tools]]
> +== Bonus - useful tools
> +
> +=== VS Code

Here, maybe use the full name, then the short version.

 === Visual Studio Code (VS Code)

> +A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
> +and explanation of how to use the script are available in contrib/vscode/README.md.

This passive voice could be made active such as:

  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.

Make a new paragraph before talking about debuggers.

> +Using the integrate debugger can be particularly helpful to understand how Git works internally.
> +It can be used to isolate some parts of code, with this you may be able to ask more precises
> +question when you are stuck. (See getting-help sections).

I would focus less on "benefits of debugging" and focus instead on
"benefits of debugging using your GUI editor". Something like this
might be a good start:

  In particular, this script enables using the VS Code visual debugger,
  including setting breakpoints in the editor.

> \ No newline at end of file

Fix this missing newline.

> diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
> index 8202d62035..f383c95e1f 100644
> --- a/contrib/vscode/README.md
> +++ b/contrib/vscode/README.md
> @@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
>  [Windows](https://code.visualstudio.com/docs/setup/windows),
>  [macOS](https://code.visualstudio.com/docs/setup/mac) and
>  [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
> -it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
> +it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
> +[debugging support](https://code.visualstudio.com/docs/editor/debugging)
> +
> +To get help about "how to personalize your settings" read:
> +[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)

These changes are pretty standard, and I have no concerns here.

>              "stopAtEntry": false,
>              "cwd": "\${workspaceFolder}",
>              "environment": [],
> -            "externalConsole": true,

And this is the necessary fix.

Thanks for working on this!

Thanks,
-Stolee