Content
- Introduction
- The Art of Writing Great PR Messages
- Conclusion
Introduction
As a computer programmer, you've probably been in a situation where you need to work with others on projects. Whether it's a project at work, school, an open-source project, or even a side project you and your friends decided to work on it.
As a computer programmer in this category, you most likely used a tool called Git as a VCS (Version Control System) and GitHub, Bit Bucket, or any of the others. If so, you must be familiar with the term called "pull request" or "PR", related to something called a branch.
Branches and PRs
A branch is like a duplicate of the main code folder. You can edit its content and then merge it with the main folder. You can also collaborate with others by merging your folder with theirs.
When merging your branch with others, you can add a nice message stating why your code should be merged. In really chill environments (say your school project or side project), this message helps the team know what exactly has changed.
It's a slightly different case if it's a work or open source project. You don't just merge your branch with the main one as that can break things. What you do instead is to create a Pull Request. In the case of a pull request, the message tells the team what will change if they merge your code and whether or not they should let it through. In short, everyone else looks at your changes and decides if they should be merged.
The Art of Writing Great PR Messages
When writing a pull request, a clear and straightforward message is important. A poorly written message can lead to confusion among team members about code changes, making them reluctant to adopt your changes. There are various things to look for when writing a great PR
Write good PRs
Great PR messages require great PRs. Ensure your PRs contain clear, straightforward, and well-written code with context. Avoid adding too many features in one PR. PRs should focus on a new feature, a bug fix, a refactored feature, feature tests, or documentation changes.
When submitting a pull request (PR), it's important to ensure that the changes made are neither too little nor too much. If the changes made are too little, it might not be considered worthy of a PR. On the other hand, if it's too much, it should be broken down into multiple PRs for better clarity.
A useful tip is to create a new branch for each PR or proposed change. Once the objective of the branch has been completed and the PR has been merged, the branch should be deleted.
For instance, if you create a branch called "login-feature", after creating and merging the login feature to the main branch, the branch should be deleted. Even if there's a change or bug fix to the login feature, the change should have its branch. This helps keep things organized and makes the process a lot cleaner.
Plan your PR message before creating the branch
Now that you've got a great PR, you need a great PR message to explain what's in the PR. A great way to always have a clear and brief PR message is to write it before writing code. Let the PR message be your guide to the changes you'll make. This makes your work easy and helps you stay on track while coding, thus making your PR message a perfect description of PR.
Use Clear Language
Always remember that not everyone who reads your PR message will have technical knowledge. So, it's best to avoid using technical terms as much as possible. Only use programming words when necessary, and always write your message as if it's being read by someone who is not a coder. This will ensure that your message is clear and easily understood by everyone.
Lastly, when writing a PR in English, use common words instead of uncommon ones. For instance, use "brief" instead of "succinct".
Add Images if necessary
There's this saying that an image is worth a thousand words. If your changes also affect design, it's not a bad idea to include pictures of the new design. Whether it's the database design, system design, or even changes to some form of front end, images go a long way in explaining what has changed.
Tag your teammates
When you want your teammates to review your code, make sure to tag them. If your teammates are also working on the same feature, they should also be tagged. Additionally, it's important to mention everyone who is involved in your change in your PR message. This will help draw attention to your change and ensure that everyone stays informed.
Follow the crowd
When writing PR messages, it's important to ensure they follow the same structure and format that other team members use. If you are contributing to an open-source project, likely, there are already guidelines in place for how PR messages should be structured. It's essential to follow these guidelines strictly to ensure clarity and consistency across the project.
Conclusion
- Writing clear and concise PR messages is crucial for getting your PRs merged
- Avoid using technical jargon and use simple language that is easy to understand
- Tag your teammates in the message if necessary
- Consider including images to help explain the changes you've made
- Following these tips will help your teammates understand your changes and make the review process more efficient.
Watch out for Part 2 and if you have any questions, feel free to reach out to me via E-mail: ikabolo59@gmail.com or Twitter
Top comments (2)
This is a really good read👍 Thanks Samuel
Thanks alot Samuel