← Back to Blog List

Fixing Outdated Docs in Git: My First Contribution

March 8, 2025 - March 12, 2025

Contributing to Git for GSoC seemed like a good goal, given my experience with related technologies and daily use of Git itself. As a first step, I decided to examine the documentation, starting with the guide aimed at new contributors: MyFirstContribution.adoc.

Spotting Discrepancies

While reading the guide and attempting to follow its examples, I encountered several inconsistencies. Some code snippets didn't compile against the current Git source, and certain instructions referred to outdated practices or interfaces. It seemed the document hadn't fully kept pace with the codebase evolution.

Since the GSoC program suggests starting with a small "microproject," updating this document felt like a suitable task. I sent an initial query to the Git mailing list to gauge if this was a reasonable approach:

The responses provided useful context. Mahendra Dani shared links to the official microproject list and other relevant resources, which was helpful for orientation.

Junio Hamano, the Git maintainer, also replied, offering clarification on the purpose and nature of microprojects within the Git community:

This feedback was instructive. It highlighted that the key wasn't seeking permission but rather identifying specific issues and proposing concrete fixes. It also emphasized that the microproject phase is primarily about learning the contribution process – communication via the mailing list, patch formatting, handling reviews – rather than just the technical change itself. The main takeaway was the need for specificity when discussing potential changes.

Getting Specific

Following that advice, I re-examined MyFirstContribution.adoc and the related code, carefully documenting the specific problems I'd found:

  1. Outdated Function Signature:

    The documentation showed the example cmd_psuh function with this signature:

    int cmd_psuh(int argc, const char **argv, const char *prefix);

    However, the current definition in builtin.h includes an additional struct repository *repo parameter:

    int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);

    This difference caused compilation errors when following the guide directly.

  2. Missing `UNUSED` Macro Information:

    The tutorial's code example didn't utilize all parameters passed to the function (e.g., argc, argv). This typically generates compiler warnings about unused parameters. The standard Git practice involves using the UNUSED macro (like UNUSED(argv);) to explicitly mark parameters as intentionally unused, but the guide didn't mention this technique.

  3. Incorrect Config Function Reference:

    The guide's "Implementation" section suggested using git_config(...) for handling configuration. In practice, particularly with the updated function signature requiring the repo struct, using repo_config(...) was necessary. While git_config exists as a wrapper, directly using repo_config seemed simpler and more appropriate for the tutorial's context.

    (Note: I initially overlooked that `git_config` acts as a wrapper, but `repo_config` still appeared more direct for this specific example.)

  4. Stale External Link:

    The document linked to an external GitHub repository (nasamuffin/git/tree/psuh) intended as a complete reference implementation. This repository hadn't been updated recently and didn't align with current Git source code (e.g., the function signature change), causing confusion during comparison.

I outlined these points and the proposed fixes in a detailed follow-up email to the mailing list:

Confirmation and Additional Pointers

This specific approach received positive confirmation. Karthik Nayak responded, agreeing with the assessment of the issues:

This response confirmed that the identified issues were valid points for improvement. Karthik also provided practical advice on handling the external link and suggested two additional minor cleanups related to the documentation.

Preparing for the Patch

With the problems clearly defined, proposed solutions discussed, and confirmation received from the community, the next step was concrete: preparing the actual changes. This involved modifying the documentation file, formatting the changes as a patch, writing a clear commit message, and submitting it via the mailing list for review – the practical application of the workflow I was here to learn.