Re: [[GSOC][PATCH v3] 3/3] docs: replace git_config with repo_config

[JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com>]

On Wed, Mar 26, 2025 at 8:07 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:
>
> >> ... better to explain _why_ each change is made in the text that
> >> precedes the sample code.  E.g.
> >>
> >>     Add `#include "config.h"` because you want to use X and Y,
> >>     and `#include "repository.h"` because you want to use Z.
> >>
> >> ...
> > In the latest patch version I've removed the comments, since we
> > already added a line above saying the user has to include
> > `repository.h` I don't think we need to go in depth into that, do let
> > me know if that is not the case, looking forward to any more feedback.
>
> It's your patch, after all.
>
> But if the reason why you added the comment was "this is a tutorial"
> as you said, I would imagine that it would help readers to say why
> a particular header is needed, when the tutorial text tells them
> that they need to add it.  From a quick look at the patch, it seems
> that the updated text says what the change did (i.e. add a header),
> which is rather obvious in the sample code, without saying why the
> addition is necessary?
>

Agreed, but there will be two things from this point, in the previous
documentation itself the header files didn't have very detailed
explanation. If I do a detailed description of the header files in
this specific tutorial/patch, the documentation will look
inconsistent.

I could do three things,

1. If these series of patches do not have any other faults/feedback,
after merging them I could start working on a second microproject
(Adding the details of header files of the whole document
consistently).

2. I could present a change in this current patch to improve the
details of the header files and re send the patch.

3. We can just leave this as is.

I'm inclined towards the first idea, as I think this will cover my
GSOC timeline and also give me some time to work on my proposal and
fulfill my requirements for GSOC at the same time, and also makes the
documentation good for newbies.

But I'm willing to work with either of these ideas, or any new method
you want to proceed with.


I think the prev email was rendered in HTML
So I resent this.


Thank you,
Jay