Treat version history as a resource #734
Conversation
When composed with care, the version history in a code repository becomes a valuable resource for the future. For example, it allows you to use `git blame` to see how files changed and understand from the commit messages _why_ such changes were made, allowing you to understand the constraints under what those changes can be made and explain why the code was written that way. To do this, you should ensure you write enough detail for someone else (or perhaps yourself in future) to understand the change in depth. You should link to external resources, but understand that those can change and so a link alone is not enough. You should rebase to avoid messy ordering, and compose your changes with care so that they can be understood at a glance.
| @@ -4,6 +4,7 @@ A guide for programming within version control. | |||
|
|
|||
| ## Best Practices | |||
|
|
|||
| - Treat the version history as a resource for the future. | |||
There was a problem hiding this comment.
Can you elaborate a bit more here? I love what you have in the PR description although that's probably too long. Maybe some kind of happy medium?
There was a problem hiding this comment.
I couldn't work out how to shorten it to fit in a line or two. Any ideas?
There was a problem hiding this comment.
Maybe something along the lines of "Explain the why and not the what"?
There was a problem hiding this comment.
An idea for incorporating some of the content from the PR description
| - Treat the version history as a resource for the future. | |
| - Treat the version history as a resource for the future. Structure your commits such that they tell the story of _why_ the change was made, so that future developers--including yourself!--can understand the constraints which influenced your decisions at the time. |
There was a problem hiding this comment.
In #738 we introduced the pattern of adding a markdown file with the reasoning and examples. You might consider doing the same.
Those would be nice blog posts too.
| @@ -4,6 +4,7 @@ A guide for programming within version control. | |||
|
|
|||
| ## Best Practices | |||
|
|
|||
| - Treat the version history as a resource for the future. | |||
There was a problem hiding this comment.
An idea for incorporating some of the content from the PR description
| - Treat the version history as a resource for the future. | |
| - Treat the version history as a resource for the future. Structure your commits such that they tell the story of _why_ the change was made, so that future developers--including yourself!--can understand the constraints which influenced your decisions at the time. |
When composed with care, the version history in a code repository becomes a valuable resource for the future.
For example, it allows you to use
git blameto see how files changed and understand from the commit messages why such changes were made, allowing you to understand the constraints under what those changes can be made and explain why the code was written that way.To do this, you should ensure you write enough detail for someone else (or perhaps yourself in future) to understand the change in depth. You should link to external resources, but understand that those can change and so a link alone is not enough. You should rebase to avoid messy ordering, and compose your changes with care so that they can be understood at a glance.