Re: [GSoC] Microproject: Updating Documentation
JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:
Show 69 quoted lines
> 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.
Show 9 quoted lines
> 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!
Show 9 quoted lines
> 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.
Show 6 quoted lines
> 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/
Show 10 quoted lines
>> 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
JAYATHEERTH K
