Fossil SCM
Clarity pass on the rebaseharm doc following the recent Hacker News thread, to address confusions that came up there.
Commit
068e26af37d7f6464b2bbb9522e140770b0198157ff15126926e51bc93b7ef2e
Parent
6e0dba257b22638…
1 file changed
+28
-16
+28
-16
| --- www/rebaseharm.md | ||
| +++ www/rebaseharm.md | ||
| @@ -325,15 +325,15 @@ | ||
| 325 | 325 | |
| 326 | 326 | 1. Edit check-in comments to fix typos or enhance clarity |
| 327 | 327 | 2. Attach supplemental notes to check-ins or whole branches |
| 328 | 328 | 3. Cross-reference check-ins with each other, or with |
| 329 | 329 | wiki, tickets, forum posts, and/or embedded documentation |
| 330 | - 4. Cause mistaken or unused branches to be hidden from | |
| 331 | - routine display | |
| 330 | + 4. Hide ill-conceived or now-unused branches from routine display | |
| 332 | 331 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 333 | 332 | system clocks |
| 334 | - 6. And so forth.... | |
| 333 | + | |
| 334 | +…and so forth. | |
| 335 | 335 | |
| 336 | 336 | These changes are accomplished not by removing or modifying existing |
| 337 | 337 | repository entries, but rather by adding new supplemental records. |
| 338 | 338 | The original incorrect or unclear inputs are preserved and are |
| 339 | 339 | readily accessible. The original history is preserved. |
| @@ -367,11 +367,11 @@ | ||
| 367 | 367 | |
| 368 | 368 | The common counterargument is that collapsed check-ins represent a |
| 369 | 369 | better world, the ideal we're striving for. What that argument overlooks |
| 370 | 370 | is that we must throw away valuable information to get there. |
| 371 | 371 | |
| 372 | -### <a name="empathy"></a>6.1 Individual check-ins support developer empathy | |
| 372 | +### <a name="empathy"></a>6.1 Individual check-ins support mutual understanding | |
| 373 | 373 | |
| 374 | 374 | Ideally, future developers of our software can understand every feature |
| 375 | 375 | in it using only context available in the version of the code they start |
| 376 | 376 | work with. Prior to widespread version control, developers had no choice |
| 377 | 377 | but to work that way. Pre-existing codebases could only be understood |
| @@ -384,11 +384,11 @@ | ||
| 384 | 384 | understand. If you have never asked yourself, "What was this code's |
| 385 | 385 | developer thinking?" you haven't been developing software for very long. |
| 386 | 386 | |
| 387 | 387 | When a developer can go back to the individual check-ins leading up to |
| 388 | 388 | the current code, they can work out the answers to such questions using |
| 389 | -only the level of empathy necessary to be a good developer. To | |
| 389 | +only the level of personal brilliance necessary to be a good developer. To | |
| 390 | 390 | understand such code using only the finished form, you are asking future |
| 391 | 391 | developers to make intuitive leaps that the original developer was |
| 392 | 392 | unable to make. In other words, you are asking your future maintenance |
| 393 | 393 | developers to be smarter than the original developers! That's a |
| 394 | 394 | beautiful wish, but there's a sharp limit to how far you can carry it. |
| @@ -497,21 +497,33 @@ | ||
| 497 | 497 | Perhaps there are some cases where a rebase-like transformation |
| 498 | 498 | is actually helpful, but those cases are rare, and when they do |
| 499 | 499 | come up, running a series of cherry-pick merges achieves the same |
| 500 | 500 | topology with several advantages: |
| 501 | 501 | |
| 502 | - 1. Cherry-pick merges preserve an honest record of history. | |
| 503 | - (They do in Fossil at least. Git's file format does not have | |
| 504 | - a slot to record cherry-pick merge history, unfortunately.) | |
| 505 | - | |
| 506 | - 2. Cherry-picks provide an opportunity to [test each new check-in | |
| 507 | - before it is committed][tbc] to the blockchain | |
| 508 | - | |
| 509 | - 3. Cherry-pick merges are "safe" in the sense that they do not | |
| 510 | - cause problems for collaborators if you do them on public branches. | |
| 511 | - | |
| 512 | - 4. Cherry-picks keep both the original and the revised check-ins, | |
| 502 | + 1. In Fossil, cherry-pick merges preserve an honest and clear record | |
| 503 | + of history. Fossil remembers where a cherry-pick came from, and | |
| 504 | + it shows this in its timeline, so other developers can understand | |
| 505 | + how a cherry-pick based commit came together. | |
| 506 | + | |
| 507 | + Git lacks the ability to remember the source of a cherry-pick as | |
| 508 | + part of the commit. This fact has no direct bearing on this | |
| 509 | + document’s thesis, but we can make a few observations. First, Git | |
| 510 | + forgets history in more cases than in rebasing. Second, if Git | |
| 511 | + remembered the source of cherry-picks in commits, Git users might | |
| 512 | + have a better argument for avoiding rebase, because they’d have an | |
| 513 | + alternative that *didn’t* lose history. | |
| 514 | + | |
| 515 | + 2. Fossil’s [test before commit philosophy][tbc] means you can test a | |
| 516 | + cherry-pick before committing it. Because Fossil allows multiple | |
| 517 | + cherry-picks in a single commit and it remembers them all, you can | |
| 518 | + do this for a complicated merge in step-wise fashion. | |
| 519 | + | |
| 520 | + Git commits cherry-picks straight to the repository, so that if it | |
| 521 | + results in a bad state, you have to do something drastic like | |
| 522 | + `git reset --hard` to repair the damage. | |
| 523 | + | |
| 524 | + 3. Cherry-picks keep both the original and the revised check-ins, | |
| 513 | 525 | so both timestamps are preserved. |
| 514 | 526 | |
| 515 | 527 | [tbc]: ./fossil-v-git.wiki#testing |
| 516 | 528 | |
| 517 | 529 | ## <a name="conclusion"></a>8.0 Summary and conclusion |
| 518 | 530 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -325,15 +325,15 @@ | |
| 325 | |
| 326 | 1. Edit check-in comments to fix typos or enhance clarity |
| 327 | 2. Attach supplemental notes to check-ins or whole branches |
| 328 | 3. Cross-reference check-ins with each other, or with |
| 329 | wiki, tickets, forum posts, and/or embedded documentation |
| 330 | 4. Cause mistaken or unused branches to be hidden from |
| 331 | routine display |
| 332 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 333 | system clocks |
| 334 | 6. And so forth.... |
| 335 | |
| 336 | These changes are accomplished not by removing or modifying existing |
| 337 | repository entries, but rather by adding new supplemental records. |
| 338 | The original incorrect or unclear inputs are preserved and are |
| 339 | readily accessible. The original history is preserved. |
| @@ -367,11 +367,11 @@ | |
| 367 | |
| 368 | The common counterargument is that collapsed check-ins represent a |
| 369 | better world, the ideal we're striving for. What that argument overlooks |
| 370 | is that we must throw away valuable information to get there. |
| 371 | |
| 372 | ### <a name="empathy"></a>6.1 Individual check-ins support developer empathy |
| 373 | |
| 374 | Ideally, future developers of our software can understand every feature |
| 375 | in it using only context available in the version of the code they start |
| 376 | work with. Prior to widespread version control, developers had no choice |
| 377 | but to work that way. Pre-existing codebases could only be understood |
| @@ -384,11 +384,11 @@ | |
| 384 | understand. If you have never asked yourself, "What was this code's |
| 385 | developer thinking?" you haven't been developing software for very long. |
| 386 | |
| 387 | When a developer can go back to the individual check-ins leading up to |
| 388 | the current code, they can work out the answers to such questions using |
| 389 | only the level of empathy necessary to be a good developer. To |
| 390 | understand such code using only the finished form, you are asking future |
| 391 | developers to make intuitive leaps that the original developer was |
| 392 | unable to make. In other words, you are asking your future maintenance |
| 393 | developers to be smarter than the original developers! That's a |
| 394 | beautiful wish, but there's a sharp limit to how far you can carry it. |
| @@ -497,21 +497,33 @@ | |
| 497 | Perhaps there are some cases where a rebase-like transformation |
| 498 | is actually helpful, but those cases are rare, and when they do |
| 499 | come up, running a series of cherry-pick merges achieves the same |
| 500 | topology with several advantages: |
| 501 | |
| 502 | 1. Cherry-pick merges preserve an honest record of history. |
| 503 | (They do in Fossil at least. Git's file format does not have |
| 504 | a slot to record cherry-pick merge history, unfortunately.) |
| 505 | |
| 506 | 2. Cherry-picks provide an opportunity to [test each new check-in |
| 507 | before it is committed][tbc] to the blockchain |
| 508 | |
| 509 | 3. Cherry-pick merges are "safe" in the sense that they do not |
| 510 | cause problems for collaborators if you do them on public branches. |
| 511 | |
| 512 | 4. Cherry-picks keep both the original and the revised check-ins, |
| 513 | so both timestamps are preserved. |
| 514 | |
| 515 | [tbc]: ./fossil-v-git.wiki#testing |
| 516 | |
| 517 | ## <a name="conclusion"></a>8.0 Summary and conclusion |
| 518 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -325,15 +325,15 @@ | |
| 325 | |
| 326 | 1. Edit check-in comments to fix typos or enhance clarity |
| 327 | 2. Attach supplemental notes to check-ins or whole branches |
| 328 | 3. Cross-reference check-ins with each other, or with |
| 329 | wiki, tickets, forum posts, and/or embedded documentation |
| 330 | 4. Hide ill-conceived or now-unused branches from routine display |
| 331 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 332 | system clocks |
| 333 | |
| 334 | …and so forth. |
| 335 | |
| 336 | These changes are accomplished not by removing or modifying existing |
| 337 | repository entries, but rather by adding new supplemental records. |
| 338 | The original incorrect or unclear inputs are preserved and are |
| 339 | readily accessible. The original history is preserved. |
| @@ -367,11 +367,11 @@ | |
| 367 | |
| 368 | The common counterargument is that collapsed check-ins represent a |
| 369 | better world, the ideal we're striving for. What that argument overlooks |
| 370 | is that we must throw away valuable information to get there. |
| 371 | |
| 372 | ### <a name="empathy"></a>6.1 Individual check-ins support mutual understanding |
| 373 | |
| 374 | Ideally, future developers of our software can understand every feature |
| 375 | in it using only context available in the version of the code they start |
| 376 | work with. Prior to widespread version control, developers had no choice |
| 377 | but to work that way. Pre-existing codebases could only be understood |
| @@ -384,11 +384,11 @@ | |
| 384 | understand. If you have never asked yourself, "What was this code's |
| 385 | developer thinking?" you haven't been developing software for very long. |
| 386 | |
| 387 | When a developer can go back to the individual check-ins leading up to |
| 388 | the current code, they can work out the answers to such questions using |
| 389 | only the level of personal brilliance necessary to be a good developer. To |
| 390 | understand such code using only the finished form, you are asking future |
| 391 | developers to make intuitive leaps that the original developer was |
| 392 | unable to make. In other words, you are asking your future maintenance |
| 393 | developers to be smarter than the original developers! That's a |
| 394 | beautiful wish, but there's a sharp limit to how far you can carry it. |
| @@ -497,21 +497,33 @@ | |
| 497 | Perhaps there are some cases where a rebase-like transformation |
| 498 | is actually helpful, but those cases are rare, and when they do |
| 499 | come up, running a series of cherry-pick merges achieves the same |
| 500 | topology with several advantages: |
| 501 | |
| 502 | 1. In Fossil, cherry-pick merges preserve an honest and clear record |
| 503 | of history. Fossil remembers where a cherry-pick came from, and |
| 504 | it shows this in its timeline, so other developers can understand |
| 505 | how a cherry-pick based commit came together. |
| 506 | |
| 507 | Git lacks the ability to remember the source of a cherry-pick as |
| 508 | part of the commit. This fact has no direct bearing on this |
| 509 | document’s thesis, but we can make a few observations. First, Git |
| 510 | forgets history in more cases than in rebasing. Second, if Git |
| 511 | remembered the source of cherry-picks in commits, Git users might |
| 512 | have a better argument for avoiding rebase, because they’d have an |
| 513 | alternative that *didn’t* lose history. |
| 514 | |
| 515 | 2. Fossil’s [test before commit philosophy][tbc] means you can test a |
| 516 | cherry-pick before committing it. Because Fossil allows multiple |
| 517 | cherry-picks in a single commit and it remembers them all, you can |
| 518 | do this for a complicated merge in step-wise fashion. |
| 519 | |
| 520 | Git commits cherry-picks straight to the repository, so that if it |
| 521 | results in a bad state, you have to do something drastic like |
| 522 | `git reset --hard` to repair the damage. |
| 523 | |
| 524 | 3. Cherry-picks keep both the original and the revised check-ins, |
| 525 | so both timestamps are preserved. |
| 526 | |
| 527 | [tbc]: ./fossil-v-git.wiki#testing |
| 528 | |
| 529 | ## <a name="conclusion"></a>8.0 Summary and conclusion |
| 530 |