Almost every developer wants to get into this amazing world of Open Source and one of the most important parts of open source contribution (and the ultimate goal after fixing the issue) is to raise a PR and get it merged. Or you might want to add some comments to the Pull Request while reviewing. Let's learn a few amazing techniques that we use while commenting or raising PR which will make the life of maintainers and the ones who have raised it easier, and will be able to take required action easily.
In the below article, we will learn 9 different markdown syntaxes that you can use to make your PR look more professional. So Let's get started!
1) Using Headers and text formatting:
You might require to add different levels of headings or need some text formatting in your PR/comment, as we do in HTML, in markdown you can use the following syntax:
The output of this will be:
2) Lists
You might need to display some items in the form of a list in a PR or on an issue's list, the way you can do it using markdown is as follows:
The output of this will be:
3) Progress
Sometimes in a PR, you might need to add the progress of the issue to mention which part of the issue is completed and which part is pending, you can use the following syntax for it:
The output of this example will be:
4) Adding Links:
In a few cases, you might want to add links to your comments or PR, just adding the link does not look professional and need to be copied and then visited, instead you can make it more readable and friendly by using the below syntax which on clicking will redirect the reviewer to the mentioned page:
The output of this example will be:
4) Using tables:
You can make your Pull Request or issue comments look good, clean and professional by making use of tables. You can do it using the below syntax:
The output of this example will be:
6) Code Blocks:
Similar to tables, you can make your Pull Request or issue comments look professional by making use of code blocks in between. You can do it using the below syntax:
The output of this example will be:
7) Add/Remove Change:
In your PR you might want to explain what you removed or what you added from/in the existing code base. There are 2 ways in which you can do that, but the 2nd one looks better and should be preferred. Let's learn with the help of some examples:
The output of this example will be:
Bonus Tip: One more advantage of using the above `diff` syntax, which is awesome and powerful is if any reviewer uses this syntax the person who raised the PR can just click on 'Accept' and GitHub will just take that change and apply it to that branch in the Pull Request.
8) Referring to a specific part of the conversation:
Sometimes people can write huge comments to explain the piece of code they liked or any specific idea they liked and another idea that they did not like among multiple ideas mentioned in the previous comment or PR.
You can refer to the specific part of the code/idea by using below syntax:
The output of this example will be:
Using this technique, make it more efficient to which part you agree with and the part you do not agree with, and hence the conversation can progress.
9) Mentioning the closed Issue ID:
Once your PR is reviewed, approved and merged you might also want to close the Issue. Instead of closing it explicitly, you can just mention the Issue ID in your comment as below:
The above code will automatically close the issue once your PR has been merged, which will save the maintainers from one additional task of closing your issue.
Bonus Tip: Try to keep your Pull Requests short, so that they are easy to read and understand and make sure your PR adds some value and doesn't waste the maintainer's time.
As most of us contribute to Open Source apart from our primary job, make sure you use the above techniques to make it very easy for the maintainers to understand your fix and get noticed by them and make their life easy.
Keep Coding and Contributing!
#WeMakeDevs #OpenSource