DEV Community

A Guide to Perfecting Pull Requests

Kara Luton on July 20, 2023

I don't know about you but I love the feeling of getting to hit the merge button on my code and sending it off to production. That's our ultimate g...
Collapse
 
pradumnasaraf profile image
Pradumna Saraf

Good stuff.

Collapse
 
chantal profile image
Chantal

Book marked this!

Collapse
 
aleixsuau profile image
Aleix Suau

Thanks for sharing Kara!

I believe that the what and why of the PR should be well described in the ticket of the tasks (Jira maybe). Its ID should be present on the name of the branch and its link in the PR comment. The how should probably be clear from the code itself(good naming, small functions, encapsulation, clear API...) documentation and the tests.

All that should minimize the need to explain that in the PR and it is probably more future proof.

Collapse
 
thumbone profile image
Bernd Wechner

Awesome stuff.

Another angle you might approach on the same theme is the technical (this covered the human side very well, and I wish it were obvious, but hey, I'm glad, given it clearly isn't to many, it's got some coverage). The technical side that still befuddles me at times is characterised by the symptom that when I issue a PR on github I am surprised by a sudden explosion in commits! Go figure, I don't understand why, and I'm keen to learn how to avoid it.

The workflow that lands one there is as follows:

  1. Fork repo on github
  2. Clone repo locally
  3. Configure two remotes: the original as "upstream" and the forked repo and "origin" (a seeming de facto norm)
  4. Branch for the intended change
  5. Develop the change (this takes a while because even though it's small, this is FOSS< one of a hundred threads runnning and interruptions and all, and eventually, it's developed and tested and happy to PR.
  6. Push to origin. Issue a PR.
  7. Upstream is now n commits ahead of origin. And something odd happens ... and I get knotted fast. This is where I'd like a neatly defined and tested workflow published. What goes wrong when upstream has moved forward here and how is it handled to produce a clean PR that is a based on the head of upstream's master again and isn't carrying a lot of commit baggage that seems to arise.

The technical workflow for managing upstream, origin and local and a local branch with a change that wants to be a PR, given upstream has moved on since branching ... is what interest me. How to get a clean PR with only the commits I intend to deliver and submit for review is the question I have not solved.

Collapse
 
stretch0 profile image
Andrew McCallum

Some great tips in here. Big fan of being your own reveiwer. I always catch something when I review my own PR. It helps avoid wasting other peoples time too

Collapse
 
samanmahmood profile image
Saman Mahmood

Great

Collapse
 
mathsena profile image
Matheus Sena

Very good!

Collapse
 
marisol88 profile image
Marisol

Great post!!

Collapse
 
fpalamour profile image
fpalamour

Thank you for this great guide. I can only agree with everything you said.

Collapse
 
eightbit profile image
Mitch

Great perspective. Thanks.

Collapse
 
vinisbs profile image
Vinicius Sena

great job !

Collapse
 
catsarebetter profile image
Hide Shidara

Wild how much effort and politics go into a pull request in a company. Good advice.

Collapse
 
2016lisali profile image
Lisa Li

Thanks for sharing