Disclaimer: I’m not a git ninja, and I’m pretty sure a lot of people have written more sophisticated things on this topic. My only qualification is having made a lot of mistakes in the past.

So in the hope of being useful, here is my take on how to contribute simply and effectively a pull request:

  • I git clone the original repo. origin/master should point to the latest and greatest, not to my soon un-maintened fork
  • I hit “fork” on github and add my fork as a remote
  • I contribute a failing test that showcase what you have in mind
  • I open a pull-request to start the discussion

The discussion can have many outcomes: I may have requested something already possible, or outside of the scope of the project, or it’s a bad idea, or it’s good idea that the maintainers will implement ASAP, or it’s a good idea that I am ready to implement myself. 

Let’s assume the later case. I do the diligent work locally. Days or weeks later, I’m back in the pull request. I have some feedback, very good, I improve my code.  What then happens especially well-maintained fast-moving projects is that I’m at this point way behind the commit I forked on. At this point I have been stuck in the past by having to do too heavy git gymnastics. (Looking at you git rebase!)

Here is a 4 steps workflow that gets the job done:

  • Pull and merge origin/master (reminder: origin is the project’s repo,)
  • Resolve conflicts, update things then commit
  • git reset --soft origin/master then commit again.
  • Force push to my repo

The commits at steps 2 and 3 will have the same content, the git history will be clean from the perspective of the maintainers of the project, and the whole thing has the nice feature to be idiot proof.

This post is also available on DEV.