JAYATHEERTH K <jayatheerthkulkarni2005@xxxxxxxxx> 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@xxxxxxxxx> wrote: >> >> Mahendra Dani <danimahendra0904@xxxxxxxxx> 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@xxxxxxxxxxxxxxxx [1]. - Rename 'Documentation/git-psuh.txt' -> 'Documentation/git-psuh.adoc'. [1]: https://public-inbox.org/git/CAJoAoZnk88ZFZFdEtUxMnUa1OZiXYOgcw8DSbB+A0LzyCPFugg@xxxxxxxxxxxxxx/ >> 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:
signature.asc
Description: PGP signature
