Skip to content

Treat version history as a resource #734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Treat version history as a resource #734

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions git/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ A guide for programming within version control.

## Best Practices

- Treat the version history as a resource for the future.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't work out how to shorten it to fit in a line or two. Any ideas?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something along the lines of "Explain the why and not the what"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An idea for incorporating some of the content from the PR description

Suggested change
- 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nickcharlton what do you think about @jutonz's suggestion and then merging this?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: I think one part of the previous suggested change highlights the intent and objective in a clear and concrete way:

Suggested change
- 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.

- Avoid merge commits by using a [rebase workflow].
- Squash multiple trivial commits into a single commit.
- Write a [good commit message].
Expand Down