Why Pull Requests can be a great tool for involving colleagues into the Decision Making Process
Effective Architecture Decisions
In one of the last newsletters Effective Architecture Decisions: From Request for Comments (RFC) to Documenting Architecture Decisions (ADR) I described why Request for Comment (RFC) and Architecture Decision Record (ADR) are highly valuable for making and documenting architecture decisions. In this blog post, I will explain why pull requests are a great tool for involving colleagues into the architecture decision making process and how to use them effectively. If you are a developer who works with Git and GitHub, you are probably familiar with the concept of pull requests. And if you are not familiar with pull requests, I would highly recommend to take the time to learn how to use it and participate in pull request conversations.
What is a Pull Request?
A pull request is a way of proposing changes to a codebase and getting feedback from other developers before merging them into the main branch. Pull requests are not only useful for ensuring code quality and preventing bugs, but also for fostering collaboration, involvement, commitment and communication among team members. To learn more about pull requests and how to use them effectively, you can check out this tutorial by GitHub.
Why Use Pull Requests?
Pull requests have many benefits when it comes to decision making. Here are some of them:
Quality of Decision by Getting Feedback: Pull requests allow you to get feedback on your decision proposal from other stakeholders who may have more experience, different perspectives, or specialized knowledge. They can help you spot errors, bugs, performance issues, security risks, or other aspects that you may have missed. By getting feedback from different perspectives and expertise, it can avoid biases that may affect their judgment. It can also help discover new ideas, alternatives, or solutions that you may not have considered otherwise.
Involvement creates commitment: Involving others in decision making can increase the acceptance of and commitment to the decisions. By giving others a voice and a chance to contribute, it can reduce resistance, conflict, or dissatisfaction that may arise from imposing changes without consultation.
Allows involving experts or decision authorities with very limited time: Topic Experts very often have very limited amount of time and cannot participate in all meetings. A pull request allows participating in the conversation asynchronously without taking part in all meetings.
Be Asynchronous: Hybrid or remote working poses some challenges for collaboration and communication among teams, which resulted in too many ineffective meetings. Pull Requests are written change proposals. Written documents allowing for asynchronous communication are especially important in a distributed, remote or hybrid working environment and support using our meeting time more effectively for things which cannot be resolved asynchronously.
Communication: Pull requests facilitate communication among team members by providing a clear and transparent record of what changes have been made, why they have been made, and how they have been reviewed. They also allow you to communicate your intentions, expectations, and assumptions to your reviewers and get their input before making any final decisions.
Documentation: Pull requests serve as documentation by explaining what each change does and how it affects. They also help you keep track of the history and progress of your project by showing who did what and when.
How to Use Pull Requests Effectively?
To make the most out of pull requests, here are some tips and best practices to follow:
Create descriptive and concise pull requests: When creating a pull request, make sure to provide enough information for your reviewers to understand what you are trying to achieve and how you have done it. Use clear and meaningful titles, summaries, and commit messages. Avoid making too many or too few changes in one pull request. Ideally, each pull request should address one problem or decision at a time.
Request reviews from relevant people: When requesting reviews for your pull request, actively choose people who have the appropriate knowledge, skills, or authority to review your changes and can provide useful feedback or approval. You can also use labels (e.g. security, TCO) to categorize your pull requests. The labeling can help other colleagues to watch for proposal and participate if they feel they can contribute to the conversation.
Respond to feedback promptly and respectfully: When receiving feedback on your pull request, be open-minded, grateful, and respectful of your reviewers' opinions and suggestions. Don't take criticism personally or argue unnecessarily. Instead, try to understand the rationale behind each comment.
How to leverage Pull Request conversations
The documentation on commenting in pull request explains how to comment on a pull request. The page covers the following topics:
How to add a general comment or a line comment to a pull request
How to edit or delete a comment on a pull request
How to reply to a comment on a pull request
How to resolve or reopen a conversation on a pull request
How to minimize or hide a comment on a pull request
How to review comments on a pull request
The author explains the motivation for a change, outlines the proposed structure and content, and asks for specific feedback on various aspects. The reviewers provide helpful suggestions, point out potential issues, and praise the good parts. The author responds to each comment, updates the Pull Request accordingly, and resolves the conversations when they are addressed. The result is a high-quality article that reflects the input and collaboration of multiple contributors.
When it comes to using these features for conversations, I would strongly recommend to use line comments, since those make conversations much easier and it is clearer when the topic has been resolved (e.g. change incorporated into the proposal).
What is a great example for leveraging Pull Requests for Decisions?
Rust Request for Comments ensure that changes are well-designed, well-documented, and well-aligned with Rust’s goals and values. They foster collaboration, communication, transparency, and accountability among the Rust community. They help to keep Rust high-quality, stable, and consistent. The Rust documentation on how to create a request for comment provides some detailed guidelines for creating a Rust RFC (request for comments), which is a document that proposes a significant change to the Rust language or libraries. You can find many examples of different RFCs in the Rust RFC repository.
Subscription: If you want to get updates, you can subscribe to the free newsletter:
Mark as not spam: : When you subscribe to the newsletter please do not forget to check your spam / junk folder. Make sure to "mark as not spam" in your email client and move it to your Inbox. Add the publication's Substack email address to your contact list. All posts will be sent from this address: ecosystem4engineering@substack.com.
✉️ Subscribe to the newsletter — if you aren’t already.
❤️ Share it — The engineering ecosystem newsletter lives thanks to word of mouth. Share the article with someone to whom it might be useful! By forwarding the email or sharing it on social media.