First Patch Submission & Learning About Commit Granularity
After identifying the specific issues in MyFirstContribution.adoc and getting confirmation from the mailing list that they were worth fixing, it was time to move from discussion to action. This meant creating the actual changes, formatting them as a patch according to Git's standards, and submitting it for review.
Bundling the Fixes: The First Attempt
My approach was straightforward: address all the points discussed in the previous email thread in one go. I updated the function signature, added the note about the UNUSED macro, switched git_config to repo_config, removed the old mentoring list link, and renamed the example file from .txt to .adoc (plus related reference updates).
I bundled these changes into a single commit. Crafting the commit message felt important it's the explanation that lives alongside the code forever. I tried to summarize the key changes clearly:
This updates MyFirstContribution.adoc to correct outdated information, improve clarity for new contributors following the guide.
Key changes:
- Updated the function signature of `cmd_psuh` to match the current Git codebase, adding `struct repository *repo` as required.
- Added a note on using the `UNUSED` macro to suppress compiler warnings for unused function parameters.
- Replaced `git_config(...)` with `repo_config(...)` in documentation, aligning with modern Git practices.
- Removed mention of the deprecated `git-mentoring@googlegroups.com`.
- Renamed `Documentation/git-psuh.txt` to `Documentation/git-psuh.adoc` to follow the correct documentation format.
- Updated `.txt` references to `.adoc` wherever applicable for consistency.
These changes make it easier for new contributors to follow the tutorial without running into compilation errors or outdated references.
Signed-off-by: K Jayatheerth
With the patch file generated (`git format-patch -1`), I sent it off to the Git mailing list using `git send-email`. Hitting send on your first patch feels like a significant step!
The Feedback Arrives: Separate Your Concerns!
The feedback loop started the next day with a reply from D. Ben Knoble. While acknowledging the value of the fixes, he immediately zeroed in on a fundamental aspect of the patch structure:
"I'm in a poor position to judge, but I suspect reviewing this commit would be easier if each bullet was a separate commit. See Documentation/SubmittingPatches [[separate-commits]] (HTML: https://git-scm.com/docs/SubmittingPatches#separate-commits)."
- D. Ben Knoble (March 13)This was the core feedback: I had bundled too many logically distinct changes into one commit. While they all related to improving the same file, they addressed separate issues:
- Updating the function signature is one logical change.
- Adding the
UNUSEDmacro explanation is another. - Switching config functions is a third.
- Removing the mailing list is a fourth.
- Renaming the file and updating references is a fifth.
Ben's point, referencing Git's own SubmittingPatches guide, was that each of these should ideally be its *own* commit. Why? It makes the review process significantly easier. Reviewers can look at each change in isolation, understand its specific purpose, and approve or suggest modifications for just that part. It also results in a much cleaner, more understandable project history. If someone later needs to know *why* the config function was changed, they can look at a commit focused solely on that, rather than wading through unrelated changes.
Ben also noted a minor wording issue in the documentation text I added, showing the level of detail reviewers often look at:
Regarding the line: "+The following line represents the function signature for any builtin/
"This line doesn't look necessary, or should at least replace the sentence immediately prior..."
- D. Ben Knoble (March 13)Learning and Adjusting
The feedback about separate commits immediately resonated. It was a fundamental part of the Git workflow that I hadn't fully internalized before submitting. Seeing it pointed out so clearly made perfect sense. My attempt to fix everything at once, while well-intentioned, wasn't aligned with best practices for collaborative development on a project like Git.
My reply acknowledged this directly:
"Actually that's an amazing point. I was thinking the same and will start a new patch with individual bullet patches within a thread as soon as possible."
"Ok I will once check and make sure the updated patch has this rectified [the wording issue]."
- My reply to Ben (March 14)So, my very first patch submission wasn't accepted as is, but that was okay. The feedback wasn't about the *quality* of the fixes themselves, but about the *structure* and *presentation* a crucial lesson in maintainable contributions. This interaction was exactly the kind of practical learning the microproject phase is designed for.
The next task was clear: go back, break down the single commit into a logical series of smaller patches, refine the wording, and resubmit. The journey continued!