There was a lot of discussion about the recent rejection of Github pull request workflow by Linus Torvalds, the father of Git (and Linux). Note that Linus does like Github, “great at hosting”. Unfortunately the submission via the pull request mechanic does not meet the standard of kernel contribution.
I’m all for lowering the barrier to contribute something useful to a software project. Sadly, these days I also witness a lot of “shoot first, ask later” attitude. Just because a project is hosted on Github, it does not mean you can fire your editor and register a pull request and be done with it. Often, the first thing I have to write to comment a pull request is (with the suitable hyperlink):
Please read the contribution guide.
Below I highlight a few good practices which should serve as a laundry list, should you want to send an improvement or a bug fix to the project maintainer. Some of them are just common sense, but then we live in a generation where common sense starts to become a rarity. In one way or another, you may observe that some maintainers are very picky about this because they need to live with what you have produced for the lifetime of the project, while you can just perfectly disappear the next day and won’t care about it.
Check first for a contribution process. Because of legal reasons, some organizations mandate a special arrangement, e.g. Contribution License Agreement (CLA). In other cases, few maintainers want the assurance that your work is really yours, i.e. not owned by your current employer. Licensing is also a tricky matter, make sure you are aware of the implication of whatever you share with an external project.
Next, observe how the past contributions were made. Is there an official guide which gives the step-by-step instruction? Or maybe it is not that formalized and thus do you have to consult the maintainer or the mailing-list? Does everything need to filed in the issue tracker? Do you need to format your patch in a certain way? Is there a ChangeLog file? By adopting the way the members of the project discusses and carries out the development, you will be easily familiar with the process.
Write a decent commit log, e.g. a model Git commit message. A short message like “Fix stuff” won’t help anyone. You may need to write in proper English and avoid e.g. txt lingo. Nowadays, many projects also require that the link to the bug/review is to be included somewhere. Look at the past commits and find the patterns there.
Follow the testing procedure. Sending a pull request which provokes tons of regressions will not impress anyone. Watch for all kind of tests, from unit tests, functional tests, code coverage, performance stress, and even coding style. Being careful with your contribution shows how you value the project and its future, you will earn some respect in due time.
Ask for some review as early as possible. Writing software is about iteration, it’s all continuous improvement and refactoring. Don’t wait until your stuff is fully ready before screaming for some feedback. Those who work on the project for a while might have a big-picture understanding which you don’t have. Showing a half-baked patch which can be polished as you learn is better than pushing a perfect improvement which later gets rejected by the maintainer.
Last but not least, remember that sharing is beautiful and it is great that you are willing to give back something to the community. However, do not forget that project maintenance is hard (that’s why you find a lot of rotten projects out there). Engage in a discussion, share responsibly, and surely world domination will be in our hand someday!
But I have no doubt, one day the sun will come out.