Find the right place

When reading Doug’s article I was wondering if pull requests are the right place for documenting changes. I agree that those need to be documented but I disagree with the place.

Pull requests should not be the place where your team have discussions! When a pull request is open it’s too late for fundamental changes. And in a fast moving team pull requests are merged before most people of the team even see them. If you have long discussions on pull request, this means your pull requests will stay open for far too long. And this violates the quoted programmers oath: #4: make incremental small releases and #6 work with high productivity.

So if you want a place for discussions, find a different way!

The idea of pull request is for someone else (1 to x people) review changes. It is not different than a review in front of the same computer, indeed I believe that pull requests are obsolete in a world of pair programming. You might still want to keep it, for example in very large organisations to get approvals from different team members to reviews impact of system changes. But at least pair programming should drastically reduce the number of reviewers needed.

So what is with all these information we want do document? Do we need them? Absolutely! But not for the team to discuss but for the future reader of your code! He needs to understand why we did things in a certain way! This could be documented via tests and well named methods but sometimes it needs more. But the pull requests comments are not part of Git history! So move them to your commit messages instead! This is also what Square is doing, check out this great blog:https://medium.com/square-corner-blog/how-square-writes-commit-messages-8e92fcbf77c9

They use the same kind of info but for commits not pull requests!