4 ms·

> I've never understood this impulse to do "branch cleanup". Why are you adding unnecessary work? Is the source repository for tracking a history of changes or

by jorams 3y ago

> I've never understood this impulse to do "branch cleanup". Why are you adding unnecessary work? Is the source repository for tracking a history of changes or is it an art exhibition? The history is an end product intended to help others (often future me) figure out when and why things changed, preferably in self-contained, well organized steps. Often my first attempt at a change does something in an illogical order, or I make related changes that later end up in a separate merge. In the short term that change in thinking is somewhat interesting. In the long term it only confuses whoever is looking through the history to figure out why something is the way it is. The stronger version of this completely discards any history when merging a feature, but I often find that to get rid of useful information.

naasking 3y ago
> The history is an end product intended to help others (often future me) figure out when and why things changed, preferably in self-contained, well organized steps. Development is often not self-contained or perfectly organized, so we shouldn't expect this of the change history either. > In the long term it only confuses whoever is looking through the history to figure out why something is the way it is. Source control is the wrong tool for this job, that's what comments and tickets are for. Source control can help you retroactively figure out how and sometimes why something evolved in a certain way, like a good archaeological tool, but we don't use crude tools when there are better tools. I've taken to literally embedding ticket numbers along with comments directly in the code and in commit comments to document exactly why code does what it does. All functional changes are tied to tickets [1], and the tickets contain the full context, and the code comments contain a summary of that rationale. Use the right tool for the job. [1] where "functional changes" means changes that can affect behaviour, rather than stylistic changes on variable naming or revising comments that have no visible effects.
- jorams 3y ago
  > Development is often not self-contained or perfectly organized, so we shouldn't expect this of the change history either. It won't ever be perfect, but that doesn't mean we shouldn't strive to get as close as possible. > Source control is the wrong tool for this job, that's what comments and tickets are for. I agree that code comments play an important part in explaining why something is the way it is. Code comments and commit messages play a different role there, but they overlap and it can be tough to balance. Roughly: commits explain changes and the decisions made to arrive at that set of changes. Comments explain the end result and the decisions relevant to explain that end result. I disagree that tickets are a better way to convey this information. Embedding references to tickets is not necessarily a bad thing, but the lifetimes of issue trackers and source code history tends to be different, so all relevant information from such references should be in the comments or commit messages.
  - naasking 3y ago
    > Roughly: commits explain changes and the decisions made to arrive at that set of changes. Comments explain the end result and the decisions relevant to explain that end result. Agreed. So a linear history doesn't seem of much use if your current code is well documented, so are all of those pushing for linear history just poor at documentation? > Embedding references to tickets is not necessarily a bad thing, but the lifetimes of issue trackers and source code history tends to be different This is why Fossil ties the ticket system along with the VCS all in one system. In the end, I think the ticket system is almost as valuable as the source code, and shouldn't be causally tossed out.
prirun 3y ago
Small "cleanup" changes required after merging a larger change are often very educational. They highlight subtle nuances in the code that were not thought of when the large change was merged. If the smaller changes were rebased to make one large commit, the edge-case history is also lost.
- jorams 3y ago
  I completely agree, which is why I'm not a fan of squash merges that remove such nuance. In practice a feature branch often ends up with roughly three sets of changes: 1. Some small commits in preparation for the bigger change, that are also desirable should the rest never end up being merged 2. The big set of changes, either in one big commit or in a handful of smaller, independent commits 3. Some (usually smaller) commits that reflect nuances thought of or discovered after the biggest batch of changes was made Most of my history cleanup serves to separate part 1 and 2 and to turn part 2 into a set of coherent steps. Depending on how things go each of these might be merged independently or all at once.
PH95VuimJjqBqy 3y ago
You might be interested in this take on rebase then https://fossil-scm.org/home/doc/trunk/www/rebaseharm.md https://fossil-scm.org/home/doc/trunk/www/rebaseharm.md > The Git documentation acknowledges this fact (in so many words) and justifies it by saying "rebasing makes for a cleaner history." I read that sentence as a tacit admission that the Git history display capabilities are weak and need active assistance from the user to keep things manageable. Surely a better approach is to record the complete ancestry of every check-in but then fix the tool to show a "clean" history in those instances where a simplified display is desirable and edifying, but retain the option to show the real, complete, messy history for cases where detail and accuracy are more important.
- jorams 3y ago
  I find this take interesting, and I agree with a lot of it. There are also a few things I don't agree with. Points 1 to 4 argue against the idea of rebasing as an alternative to merging. I agree with this to some extent, but in practice I notice that the exact point at which a branch began is rarely important. A very rough heuristic for this is "can it be rebased non-interactively?". This effectively means I like "cherry-pick merges", and it would be cool if Git remembered more about the origins of them. Rebases that do require manual adjustment are far more error-prone than merges, and I try to avoid those. Point 5 and 6.0 are the primary reason I edit history. I want my history to tell a coherent story, not just in commit messages but also in the changes themselves, and that story often doesn't perfectly match the actual road traveled to get to the end. I don't much value mistakes where I forgot to implement half a change while tired at the end of a long workday, or an ill-considered false start. Where such information is valuable I'll write it down in the commit messages of changes that implement what did end up happening. That brings me to the other points. I very much agree with 6.1 and beyond. Squashing branches removes a lot of valuable information, and it removes the ability to tell that coherent story. In particular: - There are often small changes or bug fixes that aren't really part of the set of changes, but that just happen to become most relevant while developing this feature. Depending on the specifics these could be merged separately, and I keep them separate. - Nuances discovered later in the development of a set of changes tend to offer valuable insight, so I want to keep them separate from the rest. It would be cool if Git remembered more of the specifics of how the end result was reached, but I'm not sure if I would use it much in practice.

by jorams 3y ago

naasking 3y ago

> The history is an end product intended to help others (often future me) figure out when and why things changed, preferably in self-contained, well organized steps. Development is often not self-contained or perfectly organized, so we shouldn't expect this of the change history either. > In the long term it only confuses whoever is looking through the history to figure out why something is the way it is. Source control is the wrong tool for this job, that's what comments and tickets are for. Source control can help you retroactively figure out how and sometimes why something evolved in a certain way, like a good archaeological tool, but we don't use crude tools when there are better tools. I've taken to literally embedding ticket numbers along with comments directly in the code and in commit comments to document exactly why code does what it does. All functional changes are tied to tickets [1], and the tickets contain the full context, and the code comments contain a summary of that rationale. Use the right tool for the job. [1] where "functional changes" means changes that can affect behaviour, rather than stylistic changes on variable naming or revising comments that have no visible effects.

jorams 3y ago
> Development is often not self-contained or perfectly organized, so we shouldn't expect this of the change history either. It won't ever be perfect, but that doesn't mean we shouldn't strive to get as close as possible. > Source control is the wrong tool for this job, that's what comments and tickets are for. I agree that code comments play an important part in explaining why something is the way it is. Code comments and commit messages play a different role there, but they overlap and it can be tough to balance. Roughly: commits explain changes and the decisions made to arrive at that set of changes. Comments explain the end result and the decisions relevant to explain that end result. I disagree that tickets are a better way to convey this information. Embedding references to tickets is not necessarily a bad thing, but the lifetimes of issue trackers and source code history tends to be different, so all relevant information from such references should be in the comments or commit messages.
- naasking 3y ago
  > Roughly: commits explain changes and the decisions made to arrive at that set of changes. Comments explain the end result and the decisions relevant to explain that end result. Agreed. So a linear history doesn't seem of much use if your current code is well documented, so are all of those pushing for linear history just poor at documentation? > Embedding references to tickets is not necessarily a bad thing, but the lifetimes of issue trackers and source code history tends to be different This is why Fossil ties the ticket system along with the VCS all in one system. In the end, I think the ticket system is almost as valuable as the source code, and shouldn't be causally tossed out.

prirun 3y ago

Small "cleanup" changes required after merging a larger change are often very educational. They highlight subtle nuances in the code that were not thought of when the large change was merged. If the smaller changes were rebased to make one large commit, the edge-case history is also lost.

jorams 3y ago
I completely agree, which is why I'm not a fan of squash merges that remove such nuance. In practice a feature branch often ends up with roughly three sets of changes: 1. Some small commits in preparation for the bigger change, that are also desirable should the rest never end up being merged 2. The big set of changes, either in one big commit or in a handful of smaller, independent commits 3. Some (usually smaller) commits that reflect nuances thought of or discovered after the biggest batch of changes was made Most of my history cleanup serves to separate part 1 and 2 and to turn part 2 into a set of coherent steps. Depending on how things go each of these might be merged independently or all at once.

PH95VuimJjqBqy 3y ago

You might be interested in this take on rebase then https://fossil-scm.org/home/doc/trunk/www/rebaseharm.md https://fossil-scm.org/home/doc/trunk/www/rebaseharm.md > The Git documentation acknowledges this fact (in so many words) and justifies it by saying "rebasing makes for a cleaner history." I read that sentence as a tacit admission that the Git history display capabilities are weak and need active assistance from the user to keep things manageable. Surely a better approach is to record the complete ancestry of every check-in but then fix the tool to show a "clean" history in those instances where a simplified display is desirable and edifying, but retain the option to show the real, complete, messy history for cases where detail and accuracy are more important.

jorams 3y ago
I find this take interesting, and I agree with a lot of it. There are also a few things I don't agree with. Points 1 to 4 argue against the idea of rebasing as an alternative to merging. I agree with this to some extent, but in practice I notice that the exact point at which a branch began is rarely important. A very rough heuristic for this is "can it be rebased non-interactively?". This effectively means I like "cherry-pick merges", and it would be cool if Git remembered more about the origins of them. Rebases that do require manual adjustment are far more error-prone than merges, and I try to avoid those. Point 5 and 6.0 are the primary reason I edit history. I want my history to tell a coherent story, not just in commit messages but also in the changes themselves, and that story often doesn't perfectly match the actual road traveled to get to the end. I don't much value mistakes where I forgot to implement half a change while tired at the end of a long workday, or an ill-considered false start. Where such information is valuable I'll write it down in the commit messages of changes that implement what did end up happening. That brings me to the other points. I very much agree with 6.1 and beyond. Squashing branches removes a lot of valuable information, and it removes the ability to tell that coherent story. In particular: - There are often small changes or bug fixes that aren't really part of the set of changes, but that just happen to become most relevant while developing this feature. Depending on the specifics these could be merged separately, and I keep them separate. - Nuances discovered later in the development of a set of changes tend to offer valuable insight, so I want to keep them separate from the rest. It would be cool if Git remembered more of the specifics of how the end result was reached, but I'm not sure if I would use it much in practice.