Fossil SCM
Fix typos and remove unnecessary non-ASCII characters from the rebaseharm document.
Commit
6a903b39e81e641a332f50d7238bf8ee8acf2c3e2fd8efb3ca4c2aa28514ed2a
Parent
629259df14b114c…
1 file changed
+22
-22
+22
-22
| --- www/rebaseharm.md | ||
| +++ www/rebaseharm.md | ||
| @@ -75,11 +75,11 @@ | ||
| 75 | 75 | of main like the following: |
| 76 | 76 | |
| 77 | 77 |  |
| 78 | 78 | |
| 79 | 79 | You could choose to collapse C3\' and C5\' into a single check-in |
| 80 | -as part of this rebase, but that’s a side issue we’ll deal with | |
| 80 | +as part of this rebase, but that's a side issue we'll deal with | |
| 81 | 81 | [separately](#collapsing). |
| 82 | 82 | |
| 83 | 83 | If only merge is available, one would do a merge from the concurrent |
| 84 | 84 | mainline changes into the feature branch as follows: |
| 85 | 85 | |
| @@ -144,11 +144,11 @@ | ||
| 144 | 144 | error in the code? Testing and development are often done by separate |
| 145 | 145 | groups within a larger software development organization, because |
| 146 | 146 | developers get too close to their own code to see every problem in it. |
| 147 | 147 | |
| 148 | 148 | Given that, is it better for those many eyeballs to find your problems |
| 149 | -while they’re still isolated on a feature branch, or should that vetting | |
| 149 | +while they're still isolated on a feature branch, or should that vetting | |
| 150 | 150 | wait until you finally push a collapsed version of a private working |
| 151 | 151 | branch to the parent repo? Will the many eyeballs even see those errors |
| 152 | 152 | when they’re intermingled with code implementing some tasty new feature? |
| 153 | 153 | |
| 154 | 154 | ## <a name="testing"></a>4.0 Rebase commits untested check-ins to the blockchain |
| @@ -195,14 +195,14 @@ | ||
| 195 | 195 | doing a rebase is "blasphemous" and "you're _lying_ about what |
| 196 | 196 | actually happened", but then goes on to justify rebase as follows: |
| 197 | 197 | |
| 198 | 198 | > |
| 199 | 199 | _"The opposing point of view is that the commit history is the **story of |
| 200 | -how your project was made.** You wouldn\'t publish the first draft of a | |
| 200 | +how your project was made.** You wouldn't publish the first draft of a | |
| 201 | 201 | book, and the manual for how to maintain your software deserves careful |
| 202 | 202 | editing. This is the camp that uses tools like rebase and filter-branch |
| 203 | -to tell the story in the way that’s best for future readers."_ | |
| 203 | +to tell the story in the way that's best for future readers."_ | |
| 204 | 204 | |
| 205 | 205 | The problem with this counter-argument is that it assumes you must |
| 206 | 206 | change history in order to enhance readability. |
| 207 | 207 | And, in fairness to the Git documentation authors, changing the |
| 208 | 208 | project history appears to be the only way to make editorial |
| @@ -222,11 +222,11 @@ | ||
| 222 | 222 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 223 | 223 | system clocks |
| 224 | 224 | 6. And so forth.... |
| 225 | 225 | |
| 226 | 226 | These changes are accomplishes not by removing or modifying existing |
| 227 | -repository entries, but rather by adding new supplimental records. | |
| 227 | +repository entries, but rather by adding new supplemental records. | |
| 228 | 228 | The original incorrect or unclear inputs are preserved and are |
| 229 | 229 | readily accessible. The original history is preserved. |
| 230 | 230 | But for routine display purposes, the more |
| 231 | 231 | readable edited presentation is provided. |
| 232 | 232 | |
| @@ -237,11 +237,11 @@ | ||
| 237 | 237 | |
| 238 | 238 | Unfortunately, Git does not provide the ability to add corrections |
| 239 | 239 | or clarifications to historical check-ins. Hence, once again, |
| 240 | 240 | rebase can be seen as an attempt to work around limitations |
| 241 | 241 | of Git. Wouldn't it be better to fix the tool rather than |
| 242 | -fabricate a fictious project history? | |
| 242 | +fabricate a fictitious project history? | |
| 243 | 243 | |
| 244 | 244 | ## <a name="collapsing"></a>7.0 Collapsing check-ins throws away valuable information |
| 245 | 245 | |
| 246 | 246 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 247 | 247 | collapse multiple check-ins down to a single check-in to make the |
| @@ -251,11 +251,11 @@ | ||
| 251 | 251 | actual developer psychology: ideas rarely spring forth from fingers to |
| 252 | 252 | files in faultless finished form. A wish for collapsed, finalized |
| 253 | 253 | check-ins is a wish for a counterfactual situation. |
| 254 | 254 | |
| 255 | 255 | The common counterargument is that collapsed check-ins represent a |
| 256 | -better world, the ideal we’re striving for. What that argument overlooks | |
| 256 | +better world, the ideal we're striving for. What that argument overlooks | |
| 257 | 257 | is that we must throw away valuable information to get there. |
| 258 | 258 | |
| 259 | 259 | ### <a name="empathy"></a>7.1 Individual check-ins support developer empathy |
| 260 | 260 | |
| 261 | 261 | Ideally, future developers of our software can understand every feature |
| @@ -266,39 +266,39 @@ | ||
| 266 | 266 | develop software that was easy to understand retrospectively, even if |
| 267 | 267 | they were selfish people, because they knew they might end up being |
| 268 | 268 | those future developers! |
| 269 | 269 | |
| 270 | 270 | Yet, sometimes we come upon a piece of code that we simply cannot |
| 271 | -understand. If you have never asked yourself, “What was this code’s | |
| 272 | -developer thinking?” you haven’t been developing software for very long. | |
| 271 | +understand. If you have never asked yourself,a "What was this code's | |
| 272 | +developer thinking?" you haven't been developing software for very long. | |
| 273 | 273 | |
| 274 | 274 | When a developer can go back to the individual check-ins leading up to |
| 275 | 275 | the current code, they can work out the answers to such questions using |
| 276 | 276 | only the level of empathy necessary to be a good developer. To |
| 277 | 277 | understand such code using only the finished form, you are asking future |
| 278 | 278 | developers to make intuitive leaps that the original developer was |
| 279 | 279 | unable to make. In other words, you are asking your future maintenance |
| 280 | -developers to be smarter than the original developers! That’s a | |
| 281 | -beautiful wish, but there’s a sharp limit to how far you can carry it. | |
| 280 | +developers to be smarter than the original developers! That's a | |
| 281 | +beautiful wish, but there's a sharp limit to how far you can carry it. | |
| 282 | 282 | Eventually you hit the limits of human brilliance. |
| 283 | 283 | |
| 284 | 284 | When the operation of some bit of code is not obvious, both Fossil and |
| 285 | 285 | Git let you run a [`blame`](/help?cmd=blame) on the code file to get |
| 286 | 286 | information about each line of code, and from that which check-in last |
| 287 | 287 | touched a given line of code. If you squash the check-ins on a branch |
| 288 | 288 | down to a single check-in, you throw away the information leading up to |
| 289 | 289 | that finished form. Fossil not only preserves the check-ins surrounding |
| 290 | -the one that included the line of code you’re trying to understand, its | |
| 290 | +the one that included the line of code you're trying to understand, its | |
| 291 | 291 | [superior data model][sdm] lets you see the surrounding check-ins in |
| 292 | 292 | both directions; not only what lead up to it, but what came next. Git |
| 293 | -can’t do that short of crawling the block-chain backwards from the tip | |
| 293 | +can't do that short of crawling the block-chain backwards from the tip | |
| 294 | 294 | of the branch to the check-in you’re looking at, an expensive operation. |
| 295 | 295 | |
| 296 | 296 | We believe it is easier to understand a line of code from the 10-line |
| 297 | 297 | check-in it was a part of — and then to understand the surrounding |
| 298 | 298 | check-ins as necessary — than it is to understand a 500-line check-in |
| 299 | -that collapses a whole branch’s worth of changes down to a single | |
| 299 | +that collapses a whole branch's worth of changes down to a single | |
| 300 | 300 | finished feature. |
| 301 | 301 | |
| 302 | 302 | [sdm]: ./fossil-v-git.wiki#durable |
| 303 | 303 | |
| 304 | 304 | ### <a name="bisecting"></a>7.2 Bisecting works better on small check-ins |
| @@ -317,38 +317,38 @@ | ||
| 317 | 317 | the problem. |
| 318 | 318 | |
| 319 | 319 | ### <a name="comments"></a>7.3 Multiple check-ins require multiple check-in comments |
| 320 | 320 | |
| 321 | 321 | The more comments you have from a given developer on a given body of |
| 322 | -code, the more concise documentation you have of that developer’s | |
| 322 | +code, the more concise documentation you have of that developer'as | |
| 323 | 323 | thought process. To resume the bisecting example, a developer trying to |
| 324 | 324 | work out what the original developer was thinking with a given change |
| 325 | 325 | will have more success given a check-in comment that explains what the |
| 326 | -one check-in out of ten blamed by the “bisect” command was trying to | |
| 327 | -accomplish than if they must work that out from the eleventh check-in’s | |
| 328 | -comment, which only explains the “clean” version of the collapsed | |
| 326 | +one check-in out of ten blamed by the "bisect" command was trying to | |
| 327 | +accomplish than if they must work that out from the eleventh check-in's | |
| 328 | +comment, which only explains the "clean" version of the collapsed | |
| 329 | 329 | feature. |
| 330 | 330 | |
| 331 | 331 | ### <a name="cherrypicking"></a>7.4 Cherry-picks work better with small check-ins |
| 332 | 332 | |
| 333 | 333 | While working on a new feature in one branch, you may come across a bug |
| 334 | 334 | in the pre-existing code that you need to fix in order for work on that |
| 335 | 335 | feature to proceed. You could choose to switch briefly back to the |
| 336 | 336 | parent branch, develop the fix there, check it in, then merge the parent |
| 337 | -back up to the feature branch in order to continue work, but that’s | |
| 338 | -distracting. If the fix isn’t for a critical bug, fixing it on the | |
| 339 | -parent branch can wait, so it’s better to maintain your mental working | |
| 337 | +back up to the feature branch in order to continue work, but that's | |
| 338 | +distracting. If the fix isn't for a critical bug, fixing it on the | |
| 339 | +parent branch can wait, so it's better to maintain your mental working | |
| 340 | 340 | state by fixing the problem in place on the feature branch, then check |
| 341 | 341 | the fix in on the feature branch, resume work on the feature, and later |
| 342 | 342 | merge that fix down into the parent branch along with the feature. |
| 343 | 343 | |
| 344 | 344 | But now what happens if another branch *also* needs that fix? Let us say |
| 345 | 345 | our code repository has a branch for the current stable release, a |
| 346 | 346 | development branch for the next major version, and feature branches off |
| 347 | 347 | of the development branch. If we rebase each feature branch down into |
| 348 | 348 | the development branch as a single check-in, pushing only the rebase |
| 349 | -check-in up to the parent repo, only that fix’s developer has the | |
| 349 | +check-in up to the parent repo, only that fix's developer has the | |
| 350 | 350 | information locally to perform the cherry-pick of the fix onto the |
| 351 | 351 | stable branch. |
| 352 | 352 | |
| 353 | 353 | Developers working on new features often do not care about old stable |
| 354 | 354 | versions, yet that stable version may have an end user community that |
| 355 | 355 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -75,11 +75,11 @@ | |
| 75 | of main like the following: |
| 76 | |
| 77 |  |
| 78 | |
| 79 | You could choose to collapse C3\' and C5\' into a single check-in |
| 80 | as part of this rebase, but that’s a side issue we’ll deal with |
| 81 | [separately](#collapsing). |
| 82 | |
| 83 | If only merge is available, one would do a merge from the concurrent |
| 84 | mainline changes into the feature branch as follows: |
| 85 | |
| @@ -144,11 +144,11 @@ | |
| 144 | error in the code? Testing and development are often done by separate |
| 145 | groups within a larger software development organization, because |
| 146 | developers get too close to their own code to see every problem in it. |
| 147 | |
| 148 | Given that, is it better for those many eyeballs to find your problems |
| 149 | while they’re still isolated on a feature branch, or should that vetting |
| 150 | wait until you finally push a collapsed version of a private working |
| 151 | branch to the parent repo? Will the many eyeballs even see those errors |
| 152 | when they’re intermingled with code implementing some tasty new feature? |
| 153 | |
| 154 | ## <a name="testing"></a>4.0 Rebase commits untested check-ins to the blockchain |
| @@ -195,14 +195,14 @@ | |
| 195 | doing a rebase is "blasphemous" and "you're _lying_ about what |
| 196 | actually happened", but then goes on to justify rebase as follows: |
| 197 | |
| 198 | > |
| 199 | _"The opposing point of view is that the commit history is the **story of |
| 200 | how your project was made.** You wouldn\'t publish the first draft of a |
| 201 | book, and the manual for how to maintain your software deserves careful |
| 202 | editing. This is the camp that uses tools like rebase and filter-branch |
| 203 | to tell the story in the way that’s best for future readers."_ |
| 204 | |
| 205 | The problem with this counter-argument is that it assumes you must |
| 206 | change history in order to enhance readability. |
| 207 | And, in fairness to the Git documentation authors, changing the |
| 208 | project history appears to be the only way to make editorial |
| @@ -222,11 +222,11 @@ | |
| 222 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 223 | system clocks |
| 224 | 6. And so forth.... |
| 225 | |
| 226 | These changes are accomplishes not by removing or modifying existing |
| 227 | repository entries, but rather by adding new supplimental records. |
| 228 | The original incorrect or unclear inputs are preserved and are |
| 229 | readily accessible. The original history is preserved. |
| 230 | But for routine display purposes, the more |
| 231 | readable edited presentation is provided. |
| 232 | |
| @@ -237,11 +237,11 @@ | |
| 237 | |
| 238 | Unfortunately, Git does not provide the ability to add corrections |
| 239 | or clarifications to historical check-ins. Hence, once again, |
| 240 | rebase can be seen as an attempt to work around limitations |
| 241 | of Git. Wouldn't it be better to fix the tool rather than |
| 242 | fabricate a fictious project history? |
| 243 | |
| 244 | ## <a name="collapsing"></a>7.0 Collapsing check-ins throws away valuable information |
| 245 | |
| 246 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 247 | collapse multiple check-ins down to a single check-in to make the |
| @@ -251,11 +251,11 @@ | |
| 251 | actual developer psychology: ideas rarely spring forth from fingers to |
| 252 | files in faultless finished form. A wish for collapsed, finalized |
| 253 | check-ins is a wish for a counterfactual situation. |
| 254 | |
| 255 | The common counterargument is that collapsed check-ins represent a |
| 256 | better world, the ideal we’re striving for. What that argument overlooks |
| 257 | is that we must throw away valuable information to get there. |
| 258 | |
| 259 | ### <a name="empathy"></a>7.1 Individual check-ins support developer empathy |
| 260 | |
| 261 | Ideally, future developers of our software can understand every feature |
| @@ -266,39 +266,39 @@ | |
| 266 | develop software that was easy to understand retrospectively, even if |
| 267 | they were selfish people, because they knew they might end up being |
| 268 | those future developers! |
| 269 | |
| 270 | Yet, sometimes we come upon a piece of code that we simply cannot |
| 271 | understand. If you have never asked yourself, “What was this code’s |
| 272 | developer thinking?” you haven’t been developing software for very long. |
| 273 | |
| 274 | When a developer can go back to the individual check-ins leading up to |
| 275 | the current code, they can work out the answers to such questions using |
| 276 | only the level of empathy necessary to be a good developer. To |
| 277 | understand such code using only the finished form, you are asking future |
| 278 | developers to make intuitive leaps that the original developer was |
| 279 | unable to make. In other words, you are asking your future maintenance |
| 280 | developers to be smarter than the original developers! That’s a |
| 281 | beautiful wish, but there’s a sharp limit to how far you can carry it. |
| 282 | Eventually you hit the limits of human brilliance. |
| 283 | |
| 284 | When the operation of some bit of code is not obvious, both Fossil and |
| 285 | Git let you run a [`blame`](/help?cmd=blame) on the code file to get |
| 286 | information about each line of code, and from that which check-in last |
| 287 | touched a given line of code. If you squash the check-ins on a branch |
| 288 | down to a single check-in, you throw away the information leading up to |
| 289 | that finished form. Fossil not only preserves the check-ins surrounding |
| 290 | the one that included the line of code you’re trying to understand, its |
| 291 | [superior data model][sdm] lets you see the surrounding check-ins in |
| 292 | both directions; not only what lead up to it, but what came next. Git |
| 293 | can’t do that short of crawling the block-chain backwards from the tip |
| 294 | of the branch to the check-in you’re looking at, an expensive operation. |
| 295 | |
| 296 | We believe it is easier to understand a line of code from the 10-line |
| 297 | check-in it was a part of — and then to understand the surrounding |
| 298 | check-ins as necessary — than it is to understand a 500-line check-in |
| 299 | that collapses a whole branch’s worth of changes down to a single |
| 300 | finished feature. |
| 301 | |
| 302 | [sdm]: ./fossil-v-git.wiki#durable |
| 303 | |
| 304 | ### <a name="bisecting"></a>7.2 Bisecting works better on small check-ins |
| @@ -317,38 +317,38 @@ | |
| 317 | the problem. |
| 318 | |
| 319 | ### <a name="comments"></a>7.3 Multiple check-ins require multiple check-in comments |
| 320 | |
| 321 | The more comments you have from a given developer on a given body of |
| 322 | code, the more concise documentation you have of that developer’s |
| 323 | thought process. To resume the bisecting example, a developer trying to |
| 324 | work out what the original developer was thinking with a given change |
| 325 | will have more success given a check-in comment that explains what the |
| 326 | one check-in out of ten blamed by the “bisect” command was trying to |
| 327 | accomplish than if they must work that out from the eleventh check-in’s |
| 328 | comment, which only explains the “clean” version of the collapsed |
| 329 | feature. |
| 330 | |
| 331 | ### <a name="cherrypicking"></a>7.4 Cherry-picks work better with small check-ins |
| 332 | |
| 333 | While working on a new feature in one branch, you may come across a bug |
| 334 | in the pre-existing code that you need to fix in order for work on that |
| 335 | feature to proceed. You could choose to switch briefly back to the |
| 336 | parent branch, develop the fix there, check it in, then merge the parent |
| 337 | back up to the feature branch in order to continue work, but that’s |
| 338 | distracting. If the fix isn’t for a critical bug, fixing it on the |
| 339 | parent branch can wait, so it’s better to maintain your mental working |
| 340 | state by fixing the problem in place on the feature branch, then check |
| 341 | the fix in on the feature branch, resume work on the feature, and later |
| 342 | merge that fix down into the parent branch along with the feature. |
| 343 | |
| 344 | But now what happens if another branch *also* needs that fix? Let us say |
| 345 | our code repository has a branch for the current stable release, a |
| 346 | development branch for the next major version, and feature branches off |
| 347 | of the development branch. If we rebase each feature branch down into |
| 348 | the development branch as a single check-in, pushing only the rebase |
| 349 | check-in up to the parent repo, only that fix’s developer has the |
| 350 | information locally to perform the cherry-pick of the fix onto the |
| 351 | stable branch. |
| 352 | |
| 353 | Developers working on new features often do not care about old stable |
| 354 | versions, yet that stable version may have an end user community that |
| 355 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -75,11 +75,11 @@ | |
| 75 | of main like the following: |
| 76 | |
| 77 |  |
| 78 | |
| 79 | You could choose to collapse C3\' and C5\' into a single check-in |
| 80 | as part of this rebase, but that's a side issue we'll deal with |
| 81 | [separately](#collapsing). |
| 82 | |
| 83 | If only merge is available, one would do a merge from the concurrent |
| 84 | mainline changes into the feature branch as follows: |
| 85 | |
| @@ -144,11 +144,11 @@ | |
| 144 | error in the code? Testing and development are often done by separate |
| 145 | groups within a larger software development organization, because |
| 146 | developers get too close to their own code to see every problem in it. |
| 147 | |
| 148 | Given that, is it better for those many eyeballs to find your problems |
| 149 | while they're still isolated on a feature branch, or should that vetting |
| 150 | wait until you finally push a collapsed version of a private working |
| 151 | branch to the parent repo? Will the many eyeballs even see those errors |
| 152 | when they’re intermingled with code implementing some tasty new feature? |
| 153 | |
| 154 | ## <a name="testing"></a>4.0 Rebase commits untested check-ins to the blockchain |
| @@ -195,14 +195,14 @@ | |
| 195 | doing a rebase is "blasphemous" and "you're _lying_ about what |
| 196 | actually happened", but then goes on to justify rebase as follows: |
| 197 | |
| 198 | > |
| 199 | _"The opposing point of view is that the commit history is the **story of |
| 200 | how your project was made.** You wouldn't publish the first draft of a |
| 201 | book, and the manual for how to maintain your software deserves careful |
| 202 | editing. This is the camp that uses tools like rebase and filter-branch |
| 203 | to tell the story in the way that's best for future readers."_ |
| 204 | |
| 205 | The problem with this counter-argument is that it assumes you must |
| 206 | change history in order to enhance readability. |
| 207 | And, in fairness to the Git documentation authors, changing the |
| 208 | project history appears to be the only way to make editorial |
| @@ -222,11 +222,11 @@ | |
| 222 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 223 | system clocks |
| 224 | 6. And so forth.... |
| 225 | |
| 226 | These changes are accomplishes not by removing or modifying existing |
| 227 | repository entries, but rather by adding new supplemental records. |
| 228 | The original incorrect or unclear inputs are preserved and are |
| 229 | readily accessible. The original history is preserved. |
| 230 | But for routine display purposes, the more |
| 231 | readable edited presentation is provided. |
| 232 | |
| @@ -237,11 +237,11 @@ | |
| 237 | |
| 238 | Unfortunately, Git does not provide the ability to add corrections |
| 239 | or clarifications to historical check-ins. Hence, once again, |
| 240 | rebase can be seen as an attempt to work around limitations |
| 241 | of Git. Wouldn't it be better to fix the tool rather than |
| 242 | fabricate a fictitious project history? |
| 243 | |
| 244 | ## <a name="collapsing"></a>7.0 Collapsing check-ins throws away valuable information |
| 245 | |
| 246 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 247 | collapse multiple check-ins down to a single check-in to make the |
| @@ -251,11 +251,11 @@ | |
| 251 | actual developer psychology: ideas rarely spring forth from fingers to |
| 252 | files in faultless finished form. A wish for collapsed, finalized |
| 253 | check-ins is a wish for a counterfactual situation. |
| 254 | |
| 255 | The common counterargument is that collapsed check-ins represent a |
| 256 | better world, the ideal we're striving for. What that argument overlooks |
| 257 | is that we must throw away valuable information to get there. |
| 258 | |
| 259 | ### <a name="empathy"></a>7.1 Individual check-ins support developer empathy |
| 260 | |
| 261 | Ideally, future developers of our software can understand every feature |
| @@ -266,39 +266,39 @@ | |
| 266 | develop software that was easy to understand retrospectively, even if |
| 267 | they were selfish people, because they knew they might end up being |
| 268 | those future developers! |
| 269 | |
| 270 | Yet, sometimes we come upon a piece of code that we simply cannot |
| 271 | understand. If you have never asked yourself,a "What was this code's |
| 272 | developer thinking?" you haven't been developing software for very long. |
| 273 | |
| 274 | When a developer can go back to the individual check-ins leading up to |
| 275 | the current code, they can work out the answers to such questions using |
| 276 | only the level of empathy necessary to be a good developer. To |
| 277 | understand such code using only the finished form, you are asking future |
| 278 | developers to make intuitive leaps that the original developer was |
| 279 | unable to make. In other words, you are asking your future maintenance |
| 280 | developers to be smarter than the original developers! That's a |
| 281 | beautiful wish, but there's a sharp limit to how far you can carry it. |
| 282 | Eventually you hit the limits of human brilliance. |
| 283 | |
| 284 | When the operation of some bit of code is not obvious, both Fossil and |
| 285 | Git let you run a [`blame`](/help?cmd=blame) on the code file to get |
| 286 | information about each line of code, and from that which check-in last |
| 287 | touched a given line of code. If you squash the check-ins on a branch |
| 288 | down to a single check-in, you throw away the information leading up to |
| 289 | that finished form. Fossil not only preserves the check-ins surrounding |
| 290 | the one that included the line of code you're trying to understand, its |
| 291 | [superior data model][sdm] lets you see the surrounding check-ins in |
| 292 | both directions; not only what lead up to it, but what came next. Git |
| 293 | can't do that short of crawling the block-chain backwards from the tip |
| 294 | of the branch to the check-in you’re looking at, an expensive operation. |
| 295 | |
| 296 | We believe it is easier to understand a line of code from the 10-line |
| 297 | check-in it was a part of — and then to understand the surrounding |
| 298 | check-ins as necessary — than it is to understand a 500-line check-in |
| 299 | that collapses a whole branch's worth of changes down to a single |
| 300 | finished feature. |
| 301 | |
| 302 | [sdm]: ./fossil-v-git.wiki#durable |
| 303 | |
| 304 | ### <a name="bisecting"></a>7.2 Bisecting works better on small check-ins |
| @@ -317,38 +317,38 @@ | |
| 317 | the problem. |
| 318 | |
| 319 | ### <a name="comments"></a>7.3 Multiple check-ins require multiple check-in comments |
| 320 | |
| 321 | The more comments you have from a given developer on a given body of |
| 322 | code, the more concise documentation you have of that developer'as |
| 323 | thought process. To resume the bisecting example, a developer trying to |
| 324 | work out what the original developer was thinking with a given change |
| 325 | will have more success given a check-in comment that explains what the |
| 326 | one check-in out of ten blamed by the "bisect" command was trying to |
| 327 | accomplish than if they must work that out from the eleventh check-in's |
| 328 | comment, which only explains the "clean" version of the collapsed |
| 329 | feature. |
| 330 | |
| 331 | ### <a name="cherrypicking"></a>7.4 Cherry-picks work better with small check-ins |
| 332 | |
| 333 | While working on a new feature in one branch, you may come across a bug |
| 334 | in the pre-existing code that you need to fix in order for work on that |
| 335 | feature to proceed. You could choose to switch briefly back to the |
| 336 | parent branch, develop the fix there, check it in, then merge the parent |
| 337 | back up to the feature branch in order to continue work, but that's |
| 338 | distracting. If the fix isn't for a critical bug, fixing it on the |
| 339 | parent branch can wait, so it's better to maintain your mental working |
| 340 | state by fixing the problem in place on the feature branch, then check |
| 341 | the fix in on the feature branch, resume work on the feature, and later |
| 342 | merge that fix down into the parent branch along with the feature. |
| 343 | |
| 344 | But now what happens if another branch *also* needs that fix? Let us say |
| 345 | our code repository has a branch for the current stable release, a |
| 346 | development branch for the next major version, and feature branches off |
| 347 | of the development branch. If we rebase each feature branch down into |
| 348 | the development branch as a single check-in, pushing only the rebase |
| 349 | check-in up to the parent repo, only that fix's developer has the |
| 350 | information locally to perform the cherry-pick of the fix onto the |
| 351 | stable branch. |
| 352 | |
| 353 | Developers working on new features often do not care about old stable |
| 354 | versions, yet that stable version may have an end user community that |
| 355 |