Fossil SCM
Rework the "rebase is lying" section of the "Rebase considered harmful" document to be less confrontational, while at the same time still calling out rebase for what it really is.
Commit
629259df14b114c376c5df3e7c10319f9c37571b7cee3ec2bd6fd8c11d7b6343
Parent
e07256d59e1a1b5…
1 file changed
+36
-20
+36
-20
| --- www/rebaseharm.md | ||
| +++ www/rebaseharm.md | ||
| @@ -183,11 +183,11 @@ | ||
| 183 | 183 | unique timestamps for C3' and C5'. But then you lose the information |
| 184 | 184 | about when those check-ins were originally created, which can make |
| 185 | 185 | historical analysis of changes more difficult, and might also |
| 186 | 186 | complicate prior art claims. |
| 187 | 187 | |
| 188 | -## <a name="lying"></a>6.0 Rebasing is the same as lying | |
| 188 | +## <a name="lying"></a>6.0 Rebasing is lying about the project history | |
| 189 | 189 | |
| 190 | 190 | By discarding parentage information, rebase attempts to deceive the |
| 191 | 191 | reader about how the code actually came together. |
| 192 | 192 | |
| 193 | 193 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| @@ -200,32 +200,48 @@ | ||
| 200 | 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 | 203 | to tell the story in the way that’s best for future readers."_ |
| 204 | 204 | |
| 205 | -I reject this argument utterly. | |
| 206 | -Unless your project is a work of fiction, it is not a "story" but a "history." | |
| 207 | -Honorable writers adjust their narrative to fit | |
| 208 | -history. Rebase adjusts history to fit the narrative. | |
| 209 | - | |
| 210 | -Truthful texts can be redrafted for clarity and accuracy. | |
| 211 | -Fossil supports this by providing mechanisms to fix | |
| 212 | -typos in check-in comments, attach supplemental notes, | |
| 213 | -and make other editorial changes. | |
| 214 | -The corrections are accomplished by adding | |
| 215 | -new modification records to the blockchain. The original incorrect | |
| 216 | -inputs are preserved in the blockchain and are easily accessible. | |
| 217 | -But for routine display purposes, the more readable edited | |
| 218 | -presentation is provided. A repository can be a true and accurate | |
| 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 | |
| 209 | +changes in Git. | |
| 210 | + | |
| 211 | +But it does not have to be that way. | |
| 212 | +Fossil supports improvements to "the story of how your project | |
| 213 | +was made" without changing the actual history of your project | |
| 214 | +by allowing users to: | |
| 215 | + | |
| 216 | + 1. Edit check-in comments to fix typos or enhance clarify | |
| 217 | + 2. Attaching supplemental notes to check-ins or whole branches | |
| 218 | + 3. Cross-referencing check-ins with each other, or with | |
| 219 | + wiki, tickets, forum posts, and/or embedded documentation | |
| 220 | + 4. Cause mistaken or unused branches to be hidden from | |
| 221 | + routine display | |
| 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 | + | |
| 233 | +A repository can be a true and accurate | |
| 219 | 234 | representation of history even without getting everything perfect |
| 220 | -on the first draft. | |
| 235 | +on the first draft. Those are not contradictory goals, at least | |
| 236 | +not in theory. | |
| 221 | 237 | |
| 222 | 238 | Unfortunately, Git does not provide the ability to add corrections |
| 223 | -or clarifications to historical check-ins in its blockchain. Hence, | |
| 224 | -once again, rebase can be seen as an attempt to work around limitations | |
| 225 | -of Git. Wouldn't it be better to fix the tool rather than to lie about | |
| 226 | -the project history? | |
| 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? | |
| 227 | 243 | |
| 228 | 244 | ## <a name="collapsing"></a>7.0 Collapsing check-ins throws away valuable information |
| 229 | 245 | |
| 230 | 246 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 231 | 247 | collapse multiple check-ins down to a single check-in to make the |
| 232 | 248 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -183,11 +183,11 @@ | |
| 183 | unique timestamps for C3' and C5'. But then you lose the information |
| 184 | about when those check-ins were originally created, which can make |
| 185 | historical analysis of changes more difficult, and might also |
| 186 | complicate prior art claims. |
| 187 | |
| 188 | ## <a name="lying"></a>6.0 Rebasing is the same as lying |
| 189 | |
| 190 | By discarding parentage information, rebase attempts to deceive the |
| 191 | reader about how the code actually came together. |
| 192 | |
| 193 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| @@ -200,32 +200,48 @@ | |
| 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 | I reject this argument utterly. |
| 206 | Unless your project is a work of fiction, it is not a "story" but a "history." |
| 207 | Honorable writers adjust their narrative to fit |
| 208 | history. Rebase adjusts history to fit the narrative. |
| 209 | |
| 210 | Truthful texts can be redrafted for clarity and accuracy. |
| 211 | Fossil supports this by providing mechanisms to fix |
| 212 | typos in check-in comments, attach supplemental notes, |
| 213 | and make other editorial changes. |
| 214 | The corrections are accomplished by adding |
| 215 | new modification records to the blockchain. The original incorrect |
| 216 | inputs are preserved in the blockchain and are easily accessible. |
| 217 | But for routine display purposes, the more readable edited |
| 218 | presentation is provided. A repository can be a true and accurate |
| 219 | representation of history even without getting everything perfect |
| 220 | on the first draft. |
| 221 | |
| 222 | Unfortunately, Git does not provide the ability to add corrections |
| 223 | or clarifications to historical check-ins in its blockchain. Hence, |
| 224 | once again, rebase can be seen as an attempt to work around limitations |
| 225 | of Git. Wouldn't it be better to fix the tool rather than to lie about |
| 226 | the project history? |
| 227 | |
| 228 | ## <a name="collapsing"></a>7.0 Collapsing check-ins throws away valuable information |
| 229 | |
| 230 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 231 | collapse multiple check-ins down to a single check-in to make the |
| 232 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -183,11 +183,11 @@ | |
| 183 | unique timestamps for C3' and C5'. But then you lose the information |
| 184 | about when those check-ins were originally created, which can make |
| 185 | historical analysis of changes more difficult, and might also |
| 186 | complicate prior art claims. |
| 187 | |
| 188 | ## <a name="lying"></a>6.0 Rebasing is lying about the project history |
| 189 | |
| 190 | By discarding parentage information, rebase attempts to deceive the |
| 191 | reader about how the code actually came together. |
| 192 | |
| 193 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| @@ -200,32 +200,48 @@ | |
| 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 |
| 209 | changes in Git. |
| 210 | |
| 211 | But it does not have to be that way. |
| 212 | Fossil supports improvements to "the story of how your project |
| 213 | was made" without changing the actual history of your project |
| 214 | by allowing users to: |
| 215 | |
| 216 | 1. Edit check-in comments to fix typos or enhance clarify |
| 217 | 2. Attaching supplemental notes to check-ins or whole branches |
| 218 | 3. Cross-referencing check-ins with each other, or with |
| 219 | wiki, tickets, forum posts, and/or embedded documentation |
| 220 | 4. Cause mistaken or unused branches to be hidden from |
| 221 | routine display |
| 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 | |
| 233 | A repository can be a true and accurate |
| 234 | representation of history even without getting everything perfect |
| 235 | on the first draft. Those are not contradictory goals, at least |
| 236 | not in theory. |
| 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 |
| 248 |