Git Workflow Clarification: GitHub PRs vs. The Mailing List
After sending my first patch series to the Git mailing list (and learning about the need to split it into smaller commits), I encountered another layer of the Git contribution process that initially caused some confusion: the role of GitHub Pull Requests.
Coming from projects where GitHub PRs are the standard way to propose changes, I had also opened a Pull Request on the git/git mirror repository containing my initial (bundled) commit. My thinking was that this might be needed for the final merge or for CI checks.
Enter GitGitGadget
Almost immediately after opening the PR, the automation kicked in. The GitGitGadget bot chimed in with a welcome message and some instructions. Notably, the template text added to the PR description itself contained a crucial piece of information:
This was the first hint that my understanding might be slightly off. The bot also flagged issues with my commit message formatting (line length), reinforcing the specific standards expected by the project.
"There are issues in commit d798238:
Documentation: update MyFirstContribution.adoc to fix outdated references
Lines in the body of the commit messages should be wrapped between 60 and 76 characters..."
To proceed with using GitGitGadget (if I chose to), I needed permission. Johannes Schindelin (`dscho`) kindly granted it with a simple `/allow` command.
/allow
The Confusion: PR for Merging?
Later, after realizing from the mailing list feedback (covered in the previous post) that I needed to resubmit my patch series broken down into smaller commits, I initially closed the first PR. This led to some helpful advice from Johannes about iterating:
"@jayatheerthkulkarni in the future, please force-push to the same PR. No need to close and open PRs all the time."
"To clarify: for different patch series, by all means use separate PRs. But for the same patch series, to keep every iteration together, it is paramount that you use the same PR. Only that way will GitGitGadget generate range-diffs, and reply to previous iterations, for example."
- Johannes Schindelin (dscho)This advice made sense in the context of using the PR/GitGitGadget workflow. However, since I had already submitted my patch via email using CLI tools, the fundamental question arose: *Why did I need the PR at all?* Was it still required for the merge process even if review happened on the list?
I voiced my confusion:
"I think I'm a bit confused now, I actually sent PR for ease of merge with the source code, is this not the right method?"
"I understand I can do the CI build with my own fork too but I opened a PR to merge it, do let me know if I'm doing something wrong because this is the first time I'm contributing to Git."
- My queryThe Clarification: Mailing List is King
Johannes patiently clarified the situation, pointing back to the very text the bot had added to the PR:
"@jayatheerthkulkarni the answer is in your own PR description...:
'Thanks for taking the time to contribute to Git! Please be advised that the Git community does not use github.com for their contributions. Instead, we use a mailing list (git@vger.kernel.org) for code submissions, code reviews, and bug reports. Nevertheless, you can use GitGitGadget (...) to conveniently send your Pull Requests commits to our mailing list.'"
That's when the penny truly dropped. The Git project's primary workflow discussion, review, submission happens on the *mailing list*. GitHub PRs are *not* used for merging code in the way many other projects use them.
GitGitGadget is essentially a bridge. It allows developers who prefer the GitHub interface to manage their commits in a PR and then use commands like `/submit` to format and send those commits as patches to the mailing list. It's a convenience layer, an alternative way to interact with the mailing list workflow.
My summary of understanding:
"Ok it all makes sense now... So to summarise I don't need a PR if I directly send a patch via the mailing list ( Which I have already ) and there is no need for GitHub if I'm perfectly fine with the CLI interface."
- My summaryJohannes confirmed this:
"Precisely. GitGitGadget is for those of us (me included) who are uncomfortable with sending mails via the CLI and trying to remember all the rules and conventions to get it right."
- Johannes Schindelin (dscho)Takeaway: Know Your Workflow
This was a valuable lesson. Having already sent my patches via the command line (`git format-patch`, `git send-email`), the GitHub Pull Request was entirely redundant for *my* process. It served no purpose in the Git project's merge workflow if I was using the traditional mailing list tools. While GitGitGadget and the PR interface are fantastic tools for those who prefer them, they are an *alternative* input method to the mailing list, not a required secondary step.
Understanding the central role of the mailing list is key for anyone contributing to Git. Since I was comfortable with the CLI tools for sending patches, I realized I didn't need to maintain parallel PRs. I closed the initial PR, now understanding its place (or lack thereof) in my specific contribution workflow.
With this workflow confusion cleared up, and the feedback about commit granularity received, the next step was to properly prepare and resubmit the corrected, split-up patch series to the mailing list.
"Thanks for taking the time to contribute to Git! Please be advised that the Git community does not use github.com for their contributions. Instead, we use a mailing list (git@vger.kernel.org) for code submissions, code reviews, and bug reports. Nevertheless, you can use GitGitGadget (...) to conveniently send your Pull Requests commits to our mailing list."
- GitGitGadget Bot (PR Template)