I should admit it – I am a strong supporter of the open-source community and I strongly stay behind the ideas of open source. I know – open-source projects are harder to maintain, because anybody can contribute and thus add changes to the code base. But anyway, revealing the source of a product (be it a framework or whatever) can really help a developer or even a regular user exploit the product itself and make use of its complete set of functionalities, as well as can lead to a really rapid expansion of the project if many developers swarm around it, begin to use it and, of course, decide to freely improve it.
So, speaking of the hard maintainability of open-source projects, yes – it is a drawback for sure. Since anybody can do changes to the product, it is obligatory that there is a person (or several people) who constantly scrutinize the code and have a detailed look over the changes everybody tires to apply. For that reason, there are (in the sense of Git and GitHub) the so-called pull requests which any contributor creates after having worked on the product and the party on the other side has to review, comment, then, if there are any corrections to be done, ensure that the contributor has later properly applied these changes and finally – give a prize to the contributor via merging his or her code into the whole project code base.
You can imagine then that because of the tons of lame code roaming around the Internet, contributing to an open-source project is not that easy. Actually, it is very tough and you need to know some little tricks which can help you survive in the “battle” known as a pull request.
So, pull request, what is it all about? Well, quite literally, to create a pull request means that you, as a contributor and developer, request a given person on the other side to pull your changes, additions, fixes or whatever you have done to the original code, review them and merge them to the project’s code. In order for the other person to be happy with your changes, however, there are several things that are good to know before you ever try to contribute to an open-source project. Keeping the person on the other side happy is essential in order for the pull request not to become, as mentioned before, a battle, but to finish with a simple, yet very satisfying, merge action. So, let’s start and keep in mind that the following pieces of advice are not prioritized from top to bottom or vice versa, all of them are important!
- Make sure you have spent enough time playing with the project before trying to make any changes – this is really important because it will give you the necessary expertise and knowledge about the project itself, the way it works and on what mechanisms it is based. If you are not knowledgeable about the project’s functionalities, code base and structural basics, the person reviewing your code will become quite angry if he or she spots something obvious and important you have missed. I bet you, if you do changes without actually being in terms with what you are doing, this will be a hundred percent reflected in your code and is never going to be missed by the reviewer. In other words, you have to always be sure you know what you are doing.
- Make sure you have carefully read the project’s documentation before doing any changes. Have a deeper look over the project’s docs, especially inside the articles considering how to contribute and what regulations you have to fulfill in order to get merged, how to build the project’s code, how to format your code, etc. Furthermore, reading the documentation will definitely help you dig deep inside the project, thus helping you to easily achieve the previous point as well. And never forget the old saying which has been rustling in the world of IT for ages: “Two days of debugging can save you two hours of documentation reading”. Do you agree?
- Carefully make sure you have used the formatter rules the product requires. Never ever use your own coding styles and formatter. Every open-source project of considerable size is based on already arranged formatting rules and coding styles and you must follow them. The person on the other side usually is eagle-eyed and can spot every wrong space, tab or unnecessary blank line you have left. Many open-source projects provide a formatter which you can use in your IDE, so don’t forget to install it and turn it on – it will do the job for you.
- Always make sure you have successfully built the code of the project after you apply changes. It is a must that the code of the whole project, not only the snippets and files you have added, compile and can be built properly. Having run at least one successful build of the whole project is essential, because, if the reviewer has some negative comments about your changes, you may be asked: “did you build the project?”. If you have, you can say “yes, so I’m sure this dependency issue is not happening in reality”. By this way, you can ease the person on the other side in the process of reviewing. Furthermore, if your changes are significant, though, then it would be an absolute pity if you have forgotten to build your code before creating a pull request.
- This is an optional advice, but, if you have pushed changes in more than one commit, you can squash your commits into a single one. Although the diff generated out-of-the-box for the reviewer will be the same, it will be somehow pleasant if you provide your changes packaged into a single commit. That can earn you some positive points, plus it will make the Git tree look better!
- When writing your code, try to make it as short as possible, but at the same time explanatory and self-documented. I know, this rule should be applied to all the code you ever write, always. But in the situation of contributing to an open-source project, it is a must, because the reviewer will, for sure, want to ensure your changes will be easily understood by other developers, yet without augmenting the code base too much. So, keep it simple and comprehensive – don’t apply extensive number of comments, reduce the number of variables, etc.
- If the project is already provided with unit tests, don’t forget to write a unit test for your feature/change as well. Otherwise, you will be obliged to do so anyway. And if the project is not provided with unit tests so far, why not being the first to introduce that? If I were your reviewer and saw you wanted to introduce unit tests, I would give you a high five. However, if your tests are badly formatted and so on, their existence is not enough to get you merged, so don’t forget to apply all other rules to your tests as well.
- Let’s assume that the reviewer has gone through your changes and has found an issue. You check your changes and resolve it. At this point, don’t forget to re-run a build of the whole project, no matter how small the change was. Re-compile and re-build every time you are requested to alter your code. This is your safety feature that will prevent you from receiving any (or at least many) further comments in the pull request.
- Additionally to the previous point, if you are requested to apply changes to your code, after compiling and re-building, always re-test your functionalities. Furthermore, if your change reflects a functionality that is part of a bigger one or a whole group of features, try to re-test everything on a higher level, thus ensuring the whole bunch of functionalities to which you have done changes work properly. All in all, test more than just what’s in your garden.
- Sometimes you may come to the situation of strongly disagreeing with a given comment of the reviewer. If the case is such, always first ask what are the intentions and background behind this comment. Is there something which is still under discussion or under development? Why is this approach wrong? How can I best resolve it? After you have a response carrying the reason for the negative comment and you still don’t agree, then express your point. The reviewer may need information from your side to accept the changes. So, always communicate rather than argue, because sometimes the only reason for a pull request being open for ages is bad communication.
- Before even creating a pull request, watch out for unresolved conflicts of your branch with the base branch. In other words, always keep your branch up-to-date before you come to the point of pushing changes remotely. This may save your life, because, believe me, it is a real horror to create a pull request and see GitHub giving you the message “your branch has conflicts with the base branch”. So, always stay up to date.
- Never forget (or feel lazy) to document your changes. This, actually, has a double benefit – on one hand, other developers will easily understand how to use the feature you implemented, as well as will quickly get into your code just by reading a single paragraph of text. On the other hand, you will contribute not only to the project’s code, but to its documentation as well. Isn’t that a true win-win?
- Keep in mind that many open-source projects are used in commercial products as well. In other words, many commercial products may be based or somehow make use of open-source code. Reviewers know that and that’s why they want you to be so studious and careful. However, no matter if the open-source project is used by other bigger commercial (and private) projects, the aim of all contributors and reviewers is the same – to create a high quality product. The last sentence should always be in your head when you try to contribute, that’s for sure!
Oftentimes it happens that you get negative comments on your pull request, but remember that nobody wants to reject your code, rather than everybody needs and wants your code. It is, though, your job to convince the reviewer to pull your changes and accept your kind request. Also never forget that on the other side there is a person, not a robot, and he or she may also do mistakes, so never be offensive. The people on the other side may not know you, but even if they do, this is not a factor – your code is the factor. So, never do a contribution just for the matter of being merged. I know, it is pleasant to earn green boxes for contributions in GitHub. But, come on, you earn these green contribution boxes even if your pull request is not merged, right? They reflect your activity – commits, pull requests and open issues altogether, not only your accepted contributions. Then, what do you want – a single real contribution which brings you recognition, or an infinite number of green squares next to your profile picture? To sum up, I would say that the desire for high quality needs to become your goal when contributing to anything, be it an open-source project, a commercial product or a private project just for fun. Always strive for quality!
I hope the tips and tricks above were really helpful! Now, head on and push your commits, buddy!