[GSoC] Microproject: Updating Documentation

[GSoC] Microproject: Updating Documentation

[JAYATHEERTH K]

Hey Git community, I'm Jayatheerth (he/him) you can call me Jay.

I'm pretty new to open source and since I know C, Python, Rust and
Shell scripting and experience with Git, I wanted to contribute to Git
itself.
I always wanted to contribute to open source code as I use them on a
daily basis and I would love to stay even after GSOC...

So I had a question. I went through the documentation in Git source
code as I'm new to Git and I found that there were several outdated
elements and issues.

Since Git suggests starting with a small microproject I wanted to ask
for advice if updating MyFirstContribution.adoc would be a good micro
project or am I looking in the wrong way?

Thank you,
Jay

Re: [GSoC] Microproject: Updating Documentation

[Mahendra Dani]

On Sat, Mar 8, 2025 at 9:11 PM JAYATHEERTH K
<jayatheerthkulkarni2005@gmail.com> wrote:
>
> Hey Git community, I'm Jayatheerth (he/him) you can call me Jay.
>
Hi Jay!

> I'm pretty new to open source and since I know C, Python, Rust and
> Shell scripting and experience with Git, I wanted to contribute to Git
> itself.
> I always wanted to contribute to open source code as I use them on a
> daily basis and I would love to stay even after GSOC...
>
That's amazing.

> So I had a question. I went through the documentation in Git source
> code as I'm new to Git and I found that there were several outdated
> elements and issues.
>
Ok. Can you provide references to the issues?

> Since Git suggests starting with a small microproject I wanted to ask
> for advice if updating MyFirstContribution.adoc would be a good micro
> project or am I looking in the wrong way?
>
I'd suggest trying to submit a microproject listed in [1]. Further,
please go through the General Microproject Information[2] and
MyFirstContribution[3].

> Thank you,
> Jay
>

[[ References ]]
1. https://git.github.io/SoC-2025-Microprojects/
2. https://git.github.io/General-Microproject-Information/
3. https://git-scm.com/docs/MyFirstContribution

Thanks,
Mahendra.

Re: [GSoC] Microproject: Updating Documentation

[Junio C Hamano]

Mahendra Dani <danimahendra0904@gmail.com> writes:

> I'd suggest trying to submit a microproject listed in [1]. Further,
> please go through the General Microproject Information[2] and
> MyFirstContribution[3].

All good suggestions, but we also welcome students who try to
scratch their own itch, as long as it is small enough to be suitable
as a microproject material.  And it is fine to ask if doing X
qualifies as a microproject or if it is too involved.

The primary objective for a micro-project is to get used to the
workflow, i.e. working with the community mainly via this mailing
list, how you explain your changes in your proposed commit log
message, how to work with those who gave you reviews, how your
updated submission should look like, etc., etc.  Given that, it is
rare that anything is too trivial as a microproject material, but
you would not want to choose something too involved, as it would
slow you down in learning the procedure, which is the main focus on
the microproject period.

Another thing I noticed in the original message that is worth
reacting is that you do not need to ask for permission to start
working on anything around here.  "Am I allowed to do X for my
microproject" is not the question you want to ask; rather "I see
document X says A, B, and C, but A is outdated and I think it is
better to phrase it like D.  Would it be a suitable microproject
material?" is something we can work with. Answers may depend on the
nature of A, B, C, and D and would range from "nah, A is fine and D
is not better because ...; don't do it" to "great, yes A may have
been suitable a decade ago, but no longer relevant, and D would be a
great addition", to "Yeah, I agree that A is not great, but D is not
all that better, how about E?", to "Yes that is a great suggestion,
but wouldn't it may be a bit too much as a microproject".

To solicit such productive reaction from others, you'd need to be a
bit more specific than "I see flaws and want to improve".

Thanks, and good luck with your microproject selection.

Re: [GSoC] Microproject: Updating Documentation

[JAYATHEERTH K]

Hey Junio and Mahendra, Thanks for your responses, they’ve been super
helpful in guiding me as a new contributor!

On Sun, Mar 9, 2025 at 2:59 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Mahendra Dani <danimahendra0904@gmail.com> writes:
>
> > I'd suggest trying to submit a microproject listed in [1]. Further,
> > please go through the General Microproject Information[2] and
> > MyFirstContribution[3].
>

I've gone through the links posted by Mahendra and read the micro
projects list too.
I've also explored that we as students can have our own idea as long
as it doesn't get too involved.
These emails actually cleared up a lot about how microprojects are evaluated

> All good suggestions, but we also welcome students who try to
> scratch their own itch, as long as it is small enough to be suitable
> as a microproject material.  And it is fine to ask if doing X
> qualifies as a microproject or if it is too involved.
>
> The primary objective for a micro-project is to get used to the
> workflow, i.e. working with the community mainly via this mailing
> list, how you explain your changes in your proposed commit log
> message, how to work with those who gave you reviews, how your
> updated submission should look like, etc., etc.  Given that, it is
> rare that anything is too trivial as a microproject material, but
> you would not want to choose something too involved, as it would
> slow you down in learning the procedure, which is the main focus on
> the microproject period.
>

This really helps set expectations as learning the workflow is my main
goal here, so I’ve picked small fixes that I think will help me get
familiar with the process.

> Another thing I noticed in the original message that is worth
> reacting is that you do not need to ask for permission to start
> working on anything around here.  "Am I allowed to do X for my
> microproject" is not the question you want to ask; rather "I see
> document X says A, B, and C, but A is outdated and I think it is
> better to phrase it like D.  Would it be a suitable microproject
> material?" is something we can work with. Answers may depend on the
> nature of A, B, C, and D and would range from "nah, A is fine and D
> is not better because ...; don't do it" to "great, yes A may have
> been suitable a decade ago, but no longer relevant, and D would be a
> great addition", to "Yeah, I agree that A is not great, but D is not
> all that better, how about E?", to "Yes that is a great suggestion,
> but wouldn't it may be a bit too much as a microproject".
>

Got it, I’ll focus on being specific about what I see and what I’d change.
Here’s what I found in "MyFirstContribution.adoc" and "config.h" my
proposed fixes:

1. Outdated Function Signature in Documentation In the "Adding a New
Command" section
(https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#adding-a-new-command),
the signature for cmd_psuh() is:
int cmd_psuh(int argc, const char **argv, const char *prefix);
But the current Git codebase (builtin.h) expects:
int cmd_psuh(int argc, const char **argv, const char *prefix, struct
repository *repo);
This mismatch caused compilation errors when I tried following the tutorial.
Proposed Fix: Update the signature in the doc to include struct
repository *repo.

2. Unused Parameters Handling Not Documented The tutorial code doesn’t
mention that unused parameters (argc, argv, etc.) will trigger
compiler warnings. The current Git codebase uses the UNUSED macro
(e.g., as seen in cmd_check_ref_format in builtin/check-ref-format.c)
to handle this, but the doc skips this detail.
Proposed Fix: Add a note in the doc explaining how to use the UNUSED
macro for unused arguments, and update the example code snippet to
reflect this.

3. Incorrect Config Function Reference In the "Implementation" section
(https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#implementation),
it mentions git_config(...), but config.c doesn’t define it.
I had to use repo_config(...) instead, which isn’t documented here.
Proposed Fix: Update the doc to use repo_config(...) and explain its usage.
Additional Note: I can also edit the config files to appropriately
correct the git_config() function if needed, but I’d require some
guidance as to not mess up other programs while doing this as I
believe config.c/config.h is used by a lot of other files too.

4. Outdated Reference Link The doc points to a GitHub repo
(https://github.com/nasamuffin/git/tree/psuh) as a reference
implementation,
but it’s not updated to the latest Git version, which confused me when
I tried following it.
Proposed Fix: Update the link to a maintained branch or clarify its status.


> To solicit such productive reaction from others, you'd need to be a
> bit more specific than "I see flaws and want to improve".
>

I seek feedback as to if this mail is well specified or do I need to
improve in any parameters.
I also seek feedback in terms of my understanding with Git workflow
and also with my understanding with Git codebase. Any feedback will be
great for me.

> Thanks, and good luck with your microproject selection.

Thanks again,
Jay

Re: [GSoC] Microproject: Updating Documentation

[JAYATHEERTH K]

> 3. Incorrect Config Function Reference In the "Implementation" section
> (https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#implementation),
> it mentions git_config(...), but config.c doesn’t define it.
> I had to use repo_config(...) instead, which isn’t documented here.
> Proposed Fix: Update the doc to use repo_config(...) and explain its usage.
> Additional Note: I can also edit the config files to appropriately
> correct the git_config() function if needed, but I’d require some
> guidance as to not mess up other programs while doing this as I
> believe config.c/config.h is used by a lot of other files too.
>

A small clarification on this I made a small error where I said
git_config(...) was not defined, I actually did a grep check and found
the wrapper function(#ifdef USE_THE_REPOSITORY_VARIABLE) , here's my
updated proposed fix

To update the MyFirstContribution.adoc to use repo_config as the *repo
is getting involved with the cmd_psuh. As this would be confusing for
many people at the start.

Thank you,
Jay

Re: [GSoC] Microproject: Updating Documentation

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 6687 bytes --]

JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:

> Hey Junio and Mahendra, Thanks for your responses, they’ve been super
> helpful in guiding me as a new contributor!
>
> On Sun, Mar 9, 2025 at 2:59 AM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Mahendra Dani <danimahendra0904@gmail.com> writes:
>>
>> > I'd suggest trying to submit a microproject listed in [1]. Further,
>> > please go through the General Microproject Information[2] and
>> > MyFirstContribution[3].
>>
>
> I've gone through the links posted by Mahendra and read the micro
> projects list too.
> I've also explored that we as students can have our own idea as long
> as it doesn't get too involved.
> These emails actually cleared up a lot about how microprojects are evaluated
>
>> All good suggestions, but we also welcome students who try to
>> scratch their own itch, as long as it is small enough to be suitable
>> as a microproject material.  And it is fine to ask if doing X
>> qualifies as a microproject or if it is too involved.
>>
>> The primary objective for a micro-project is to get used to the
>> workflow, i.e. working with the community mainly via this mailing
>> list, how you explain your changes in your proposed commit log
>> message, how to work with those who gave you reviews, how your
>> updated submission should look like, etc., etc.  Given that, it is
>> rare that anything is too trivial as a microproject material, but
>> you would not want to choose something too involved, as it would
>> slow you down in learning the procedure, which is the main focus on
>> the microproject period.
>>
>
> This really helps set expectations as learning the workflow is my main
> goal here, so I’ve picked small fixes that I think will help me get
> familiar with the process.
>
>> Another thing I noticed in the original message that is worth
>> reacting is that you do not need to ask for permission to start
>> working on anything around here.  "Am I allowed to do X for my
>> microproject" is not the question you want to ask; rather "I see
>> document X says A, B, and C, but A is outdated and I think it is
>> better to phrase it like D.  Would it be a suitable microproject
>> material?" is something we can work with. Answers may depend on the
>> nature of A, B, C, and D and would range from "nah, A is fine and D
>> is not better because ...; don't do it" to "great, yes A may have
>> been suitable a decade ago, but no longer relevant, and D would be a
>> great addition", to "Yeah, I agree that A is not great, but D is not
>> all that better, how about E?", to "Yes that is a great suggestion,
>> but wouldn't it may be a bit too much as a microproject".
>>
>
> Got it, I’ll focus on being specific about what I see and what I’d change.
> Here’s what I found in "MyFirstContribution.adoc" and "config.h" my
> proposed fixes:
>
> 1. Outdated Function Signature in Documentation In the "Adding a New
> Command" section
> (https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#adding-a-new-command),
> the signature for cmd_psuh() is:
> int cmd_psuh(int argc, const char **argv, const char *prefix);
> But the current Git codebase (builtin.h) expects:
> int cmd_psuh(int argc, const char **argv, const char *prefix, struct
> repository *repo);
> This mismatch caused compilation errors when I tried following the tutorial.
> Proposed Fix: Update the signature in the doc to include struct
> repository *repo.
>

Yes, this would be nice for users who try to follow the guide.

> 2. Unused Parameters Handling Not Documented The tutorial code doesn’t
> mention that unused parameters (argc, argv, etc.) will trigger
> compiler warnings. The current Git codebase uses the UNUSED macro
> (e.g., as seen in cmd_check_ref_format in builtin/check-ref-format.c)
> to handle this, but the doc skips this detail.
> Proposed Fix: Add a note in the doc explaining how to use the UNUSED
> macro for unused arguments, and update the example code snippet to
> reflect this.
>

This seems worthwhile too!

> 3. Incorrect Config Function Reference In the "Implementation" section
> (https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#implementation),
> it mentions git_config(...), but config.c doesn’t define it.
> I had to use repo_config(...) instead, which isn’t documented here.
> Proposed Fix: Update the doc to use repo_config(...) and explain its usage.
> Additional Note: I can also edit the config files to appropriately
> correct the git_config() function if needed, but I’d require some
> guidance as to not mess up other programs while doing this as I
> believe config.c/config.h is used by a lot of other files too.

I think for new commands and also for new users, it is not worthwhile to
get into how the `USE_THE_REPOSITORY_VARIABLE` macro works.

So I think it'd be best to modify the documentation to use
'repo_config()' as you suggested here.

> 4. Outdated Reference Link The doc points to a GitHub repo
> (https://github.com/nasamuffin/git/tree/psuh) as a reference
> implementation,
> but it’s not updated to the latest Git version, which confused me when
> I tried following it.
> Proposed Fix: Update the link to a maintained branch or clarify its status.

This is a bit hard, since this is linked to an external repository.
Generally the code referred to in this document doesn't seldom change,
so I think the easiest way to update this would be to raise a PR to
Emily's repository with the update, so the link could stay the same.
CC'd Emily in this email.

I also see some more potential fixes to the documentation, which you
could also overtake (if you wish too :))
- Remove git-mentoring@googlegroups.com [1].
- Rename 'Documentation/git-psuh.txt' -> 'Documentation/git-psuh.adoc'.

[1]: https://public-inbox.org/git/CAJoAoZnk88ZFZFdEtUxMnUa1OZiXYOgcw8DSbB+A0LzyCPFugg@mail.gmail.com/

>> To solicit such productive reaction from others, you'd need to be a
>> bit more specific than "I see flaws and want to improve".
>>
>
> I seek feedback as to if this mail is well specified or do I need to
> improve in any parameters.
> I also seek feedback in terms of my understanding with Git workflow
> and also with my understanding with Git codebase. Any feedback will be
> great for me.
>

I think the changes you suggested would be great to have. Looking
forward to the patche[s].

>> Thanks, and good luck with your microproject selection.
>
> Thanks again,
> Jay

Thanks for fixing documentation, it is very important to keep them
updated!

Karthik

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [GSoC] Microproject: Updating Documentation

[JAYATHEERTH K]

Hey Karthik,

I've looked into the mail and have added a PR to Git [1]
I also sent an email [2] starting a new thread with the patch details.

1 - https://github.com/git/git/pull/1913
2- https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/T/#u

Looking forward to feedback.

Thank you,
Jay



On Tue, Mar 11, 2025 at 3:15 AM Karthik Nayak <karthik.188@gmail.com> wrote:
>
> JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:
>
> > Hey Junio and Mahendra, Thanks for your responses, they’ve been super
> > helpful in guiding me as a new contributor!
> >
> > On Sun, Mar 9, 2025 at 2:59 AM Junio C Hamano <gitster@pobox.com> wrote:
> >>
> >> Mahendra Dani <danimahendra0904@gmail.com> writes:
> >>
> >> > I'd suggest trying to submit a microproject listed in [1]. Further,
> >> > please go through the General Microproject Information[2] and
> >> > MyFirstContribution[3].
> >>
> >
> > I've gone through the links posted by Mahendra and read the micro
> > projects list too.
> > I've also explored that we as students can have our own idea as long
> > as it doesn't get too involved.
> > These emails actually cleared up a lot about how microprojects are evaluated
> >
> >> All good suggestions, but we also welcome students who try to
> >> scratch their own itch, as long as it is small enough to be suitable
> >> as a microproject material.  And it is fine to ask if doing X
> >> qualifies as a microproject or if it is too involved.
> >>
> >> The primary objective for a micro-project is to get used to the
> >> workflow, i.e. working with the community mainly via this mailing
> >> list, how you explain your changes in your proposed commit log
> >> message, how to work with those who gave you reviews, how your
> >> updated submission should look like, etc., etc.  Given that, it is
> >> rare that anything is too trivial as a microproject material, but
> >> you would not want to choose something too involved, as it would
> >> slow you down in learning the procedure, which is the main focus on
> >> the microproject period.
> >>
> >
> > This really helps set expectations as learning the workflow is my main
> > goal here, so I’ve picked small fixes that I think will help me get
> > familiar with the process.
> >
> >> Another thing I noticed in the original message that is worth
> >> reacting is that you do not need to ask for permission to start
> >> working on anything around here.  "Am I allowed to do X for my
> >> microproject" is not the question you want to ask; rather "I see
> >> document X says A, B, and C, but A is outdated and I think it is
> >> better to phrase it like D.  Would it be a suitable microproject
> >> material?" is something we can work with. Answers may depend on the
> >> nature of A, B, C, and D and would range from "nah, A is fine and D
> >> is not better because ...; don't do it" to "great, yes A may have
> >> been suitable a decade ago, but no longer relevant, and D would be a
> >> great addition", to "Yeah, I agree that A is not great, but D is not
> >> all that better, how about E?", to "Yes that is a great suggestion,
> >> but wouldn't it may be a bit too much as a microproject".
> >>
> >
> > Got it, I’ll focus on being specific about what I see and what I’d change.
> > Here’s what I found in "MyFirstContribution.adoc" and "config.h" my
> > proposed fixes:
> >
> > 1. Outdated Function Signature in Documentation In the "Adding a New
> > Command" section
> > (https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#adding-a-new-command),
> > the signature for cmd_psuh() is:
> > int cmd_psuh(int argc, const char **argv, const char *prefix);
> > But the current Git codebase (builtin.h) expects:
> > int cmd_psuh(int argc, const char **argv, const char *prefix, struct
> > repository *repo);
> > This mismatch caused compilation errors when I tried following the tutorial.
> > Proposed Fix: Update the signature in the doc to include struct
> > repository *repo.
> >
>
> Yes, this would be nice for users who try to follow the guide.
>
> > 2. Unused Parameters Handling Not Documented The tutorial code doesn’t
> > mention that unused parameters (argc, argv, etc.) will trigger
> > compiler warnings. The current Git codebase uses the UNUSED macro
> > (e.g., as seen in cmd_check_ref_format in builtin/check-ref-format.c)
> > to handle this, but the doc skips this detail.
> > Proposed Fix: Add a note in the doc explaining how to use the UNUSED
> > macro for unused arguments, and update the example code snippet to
> > reflect this.
> >
>
> This seems worthwhile too!
>
> > 3. Incorrect Config Function Reference In the "Implementation" section
> > (https://github.com/git/git/blob/master/Documentation/MyFirstContribution.adoc#implementation),
> > it mentions git_config(...), but config.c doesn’t define it.
> > I had to use repo_config(...) instead, which isn’t documented here.
> > Proposed Fix: Update the doc to use repo_config(...) and explain its usage.
> > Additional Note: I can also edit the config files to appropriately
> > correct the git_config() function if needed, but I’d require some
> > guidance as to not mess up other programs while doing this as I
> > believe config.c/config.h is used by a lot of other files too.
>
> I think for new commands and also for new users, it is not worthwhile to
> get into how the `USE_THE_REPOSITORY_VARIABLE` macro works.
>
> So I think it'd be best to modify the documentation to use
> 'repo_config()' as you suggested here.
>
> > 4. Outdated Reference Link The doc points to a GitHub repo
> > (https://github.com/nasamuffin/git/tree/psuh) as a reference
> > implementation,
> > but it’s not updated to the latest Git version, which confused me when
> > I tried following it.
> > Proposed Fix: Update the link to a maintained branch or clarify its status.
>
> This is a bit hard, since this is linked to an external repository.
> Generally the code referred to in this document doesn't seldom change,
> so I think the easiest way to update this would be to raise a PR to
> Emily's repository with the update, so the link could stay the same.
> CC'd Emily in this email.
>
> I also see some more potential fixes to the documentation, which you
> could also overtake (if you wish too :))
> - Remove git-mentoring@googlegroups.com [1].
> - Rename 'Documentation/git-psuh.txt' -> 'Documentation/git-psuh.adoc'.
>
> [1]: https://public-inbox.org/git/CAJoAoZnk88ZFZFdEtUxMnUa1OZiXYOgcw8DSbB+A0LzyCPFugg@mail.gmail.com/
>
> >> To solicit such productive reaction from others, you'd need to be a
> >> bit more specific than "I see flaws and want to improve".
> >>
> >
> > I seek feedback as to if this mail is well specified or do I need to
> > improve in any parameters.
> > I also seek feedback in terms of my understanding with Git workflow
> > and also with my understanding with Git codebase. Any feedback will be
> > great for me.
> >
>
> I think the changes you suggested would be great to have. Looking
> forward to the patche[s].
>
> >> Thanks, and good luck with your microproject selection.
> >
> > Thanks again,
> > Jay
>
> Thanks for fixing documentation, it is very important to keep them
> updated!
>
> Karthik