GitHub PR process - herding cats

[Sergei Grichine]

Hi All,

We had an interesting discussion tonight in the ROS2 SIG about contributing to a project.

I think it deserves some clarification.

There are two actors:

• Maintainer — the original owner of a GitHub repository (for example, the author of a RoboClaw driver)
• Contributor — a person who forked the repository, introduced changes (e.g., bug fixes), and wants those changes merged into the Maintainer’s version (the “upstream”)

Let’s not focus on how annoyed or offended a Maintainer might be upon discovering that their code wasn’t perfect to begin with. Instead, let’s consider a normal, civilized process for handling this surge of unsolicited creativity.

First, the Contributor should identify a clean, working (i.e., tested) branch in their fork and review the changes they’ve made. This is usually the main branch. Tools like meld are great for comparing their code with the original.

Second, create a new branch — for example, pull_req_1 — based on your main to “freeze” the contribution. Any final adjustments can be made here (for example, removing overly creative comments left behind by Claude).

Next, it’s time to open a Pull Request (PR). There’s nothing scary about it — just a click and (optionally) a friendly description. It’s a good idea to allow the Maintainer to edit your branch; it’s isolated anyway and can be deleted later. Once you click “Submit,” the Maintainer is notified, and the wheels start turning.

At this point, the PR takes on a life of its own. It’s easily accessible in the Maintainer’s repository, with full support for comments, discussions, and code comparisons — which is, after all, GitHub’s main purpose.

Once the Maintainer accepts the changes, they are merged into their branch (usually main), and you will be notified. The PR remains as a closed record, but your working branch is now obsolete and should normally be deleted. You will clone the Maintainer's code and you both will be happy ever after - till the next PR, of course.

For examples of typical PRs, see: 

• https://github.com/flynneva/bno055/pull/83
• https://github.com/PX4/PX4-Autopilot/pulls?q=slgrobotics+is%3Aclosed
• https://github.com/PX4/PX4-Autopilot/pull/21678

Why did I mention herding cats? Go figure...

Best Regards,

-- Sergei

[Chris Albertson]

You described one process.  There is another.

You clone a repository, fix something, and then contact the maintainer.  He never replies.   This is by far the most common scenario.

[Sergei Grichine]

Chris,

"...contact the maintainer. He never replies..."

You’re right—but there’s a catch. Let’s talk about motivation.

I assume that both the Maintainer and the Contributor are Engineers, or at least aspire to be. The days when engineers stood under a bridge while a train tested its strength, or took their own lives if their skyscraper tilted, are behind us. We don’t do that anymore. However, I still see that same sense of pride and workmanship in some of us today. In the worst case, we all want some bananas for showing off.

The Maintainer put his work on GitHub for the world to see, use, and—ouch—test, debug, or ask Claude to "harshly criticize." He is effectively on Zoom now, in a global meeting. A well-submitted, valid PR is a spotlight; he has been asked a question while the audience watches. Will he just walk away? He’d better have his pants on. Ignoring it is a permanent mark against his "GitHub Karma." The PR remains there as a sore spot, forever.

The Contributor is also in the spotlight. Once the PR is submitted, his testing, code fixes, and comments are open for public discussion. If ignored, he can politely fade away, but his fixes remain available for everyone to see. The branch stays there, un-deleted. If people like the fixes, they can simply clone that branch and go. Was his PR any good? Was he a good professional? The world sees everything. A good PR will be bumped by others.

This puts pressure on both parties to conclude the matter professionally and peacefully through reviews, discussion, and ultimately, a merge - ASAP. That is, if they are both Engineers and not just cats.

Why did I mention herding cats? Go figure...

Best Regards,

-- Sergei

--
You received this message because you are subscribed to the Google Groups "HomeBrew Robotics Club" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hbrobotics+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/hbrobotics/8F1A2DC9-7E64-4608-97E9-B21B479E7272%40gmail.com.