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.
|
|
||
| ## 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.
There was a problem hiding this comment.
@nickcharlton what do you think about @jutonz's suggestion and then merging this?
|
|
||
| ## 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. |
vburzynski
left a comment
vburzynski
left a comment
There was a problem hiding this comment.
I feel like the PR description and details from the discussion could make for a great "guideline page". What would you think about keeping the bullet point succinct and to the point with a clear actionable phrasing while putting the reasoning into a linked sub-page?
|
|
||
| ## Best Practices | ||
|
|
||
| - Treat the version history as a resource for the future. |
There was a problem hiding this comment.
suggestion: I think one part of the previous suggested change highlights the intent and objective in a clear and concrete way:
| - Treat the version history as a resource for the future. | |
| - Structure commits to tell the story of why the change was made |
The rest of the reasoning reads as a great start of a "guideline page" to expound on the reasoning behind why it's a good guideline to follow...
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's a few examples of guideline pages being broken out in the Ruby guides README.md and I think some other recent PRs as well.
|
I've been getting a lot of value by pointing LLMs at version history to understand context behind changes. It's really good at finding relevant commits given a fuzzy description, tracking a set of changes, or describing the evolution of a pattern. If anything, this valuable history is now become more accessible and legible. I double endorse this PR! |
7 participants
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.