Pull Requests Volume 2: Giving Great Pull Request Reviews
Pull Requests Volume 1: Writing a Great Pull Request
The real benefit of doing this is it gives your team a chance to learn something. It gives anyone on your team who’s reviewing the code a chance to learn about the issue you faced, how you figured it out, and how you implemented the feature or bugfix. Yes, all of that is in the code itself, but here you’ve just provided a natural language paragraph explaining it. You’ve now created a little artifact the team can refer to. In a good description, you need to tell the reviewer: What the pull request does. How to test it. Any notes or caveats.