Fossil SCM
Further improvements to the hashpolicy doc: spelling, grammar, and clarity tweaks.
Commit
e07256d59e1a1b5124bdbb523ce875f0736b339fb981e3905a25c148373ed1ec
Parent
4fdc8db06a3043a…
1 file changed
+26
-27
+26
-27
| --- www/hashpolicy.wiki | ||
| +++ www/hashpolicy.wiki | ||
| @@ -13,12 +13,12 @@ | ||
| 13 | 13 | * Legacy repositories will continue working just as |
| 14 | 14 | they always have, without any conversions or upgrades. |
| 15 | 15 | * Historical check-ins will keep their same historical |
| 16 | 16 | SHA1 names. |
| 17 | 17 | * New check-ins will get more secure SHA3-256 hash names. |
| 18 | - * Your workflow will be unchanged. | |
| 19 | 18 | * Everything will continue as if nothing happened. |
| 19 | + * Your workflow will be unchanged. | |
| 20 | 20 | |
| 21 | 21 | But if you are curious and want a deeper understanding of what is |
| 22 | 22 | going on, read on... |
| 23 | 23 | |
| 24 | 24 | |
| @@ -85,13 +85,13 @@ | ||
| 85 | 85 | To be clear: Fossil (version 2.0 and later) |
| 86 | 86 | allows the SHA1 and SHA3 hashes to be mixed within |
| 87 | 87 | the same repository. Older check-ins, created years ago, |
| 88 | 88 | continue to be named using their legacy SHA1 hashes while |
| 89 | 89 | newer check-ins are named using modern SHA3 hashes. There |
| 90 | -is not need to "convert" a repository from SHA1 over to SHA3. | |
| 90 | +is no need to "convert" a repository from SHA1 over to SHA3. | |
| 91 | 91 | You can see this in Fossil itself. The recent |
| 92 | -[9d9ef82234f63758] check-in uses a SHA3 hash where as the older | |
| 92 | +[9d9ef82234f63758] check-in uses a SHA3 hash whereas the older | |
| 93 | 93 | [1669115ab9d05c18] check-in uses a SHA1 hash. |
| 94 | 94 | |
| 95 | 95 | Other than permitting the use of SHA3 in addition to SHA1, there |
| 96 | 96 | were no file format changes in Fossil version 2.0 relative |
| 97 | 97 | to the previous version 1.37. Both Fossil 2.0 and Fossil 1.37 read |
| @@ -112,11 +112,11 @@ | ||
| 112 | 112 | <td valign='top'>sha1</td> |
| 113 | 113 | <td>Name all new artifacts using the (Hardened) SHA1 hash algorithm.</td> |
| 114 | 114 | </tr> |
| 115 | 115 | <tr> |
| 116 | 116 | <td valign='top'>auto</td> |
| 117 | -<td>Name new artifacts using the SHA1 hash algorithm. But if any | |
| 117 | +<td>Name new artifacts using the SHA1 hash algorithm, but if any | |
| 118 | 118 | artifacts are encountered which are already named using SHA3, then |
| 119 | 119 | automatically switch the hash policy to "sha3"</td> |
| 120 | 120 | </tr> |
| 121 | 121 | <tr> |
| 122 | 122 | <td valign='top'>sha3</td> |
| @@ -128,11 +128,11 @@ | ||
| 128 | 128 | <tr> |
| 129 | 129 | <td valign='top'>sha3-only</td> |
| 130 | 130 | <td>Name new artifacts using the SHA3 hash algorithm even if the artifact |
| 131 | 131 | already has a SHA1 name. In other words, force the use of SHA3. This can |
| 132 | 132 | cause some artifacts to be added to the repository twice, once under their |
| 133 | -SHA1 name and again under their SHA3 name. But delta compression will | |
| 133 | +SHA1 name and again under their SHA3 name, but delta compression will | |
| 134 | 134 | prevent that from causing repository size problems.</td> |
| 135 | 135 | </tr> |
| 136 | 136 | <tr> |
| 137 | 137 | <td valign='top'>shun-sha1</td> |
| 138 | 138 | <td>Like "sha3-only" but at this level do not accept a push of SHA1-named |
| @@ -140,20 +140,22 @@ | ||
| 140 | 140 | that artifact is discarded and ignored. |
| 141 | 141 | </tr> |
| 142 | 142 | </table> |
| 143 | 143 | |
| 144 | 144 | For Fossil 2.0, and obviously also for Fossil 1.37 and before, the |
| 145 | -only hash policy supported was "sha1". All new artifacts were named | |
| 146 | -using their SHA1 hash. | |
| 147 | -Even though Fossil 2.0 was capable of understanding SHA3 hashes, it | |
| 145 | +only hash policy supported was the one now called "sha1", meaning that | |
| 146 | +all new artifacts were named | |
| 147 | +using a SHA1 hash. | |
| 148 | +Even though Fossil 2.0 added the capability of understanding SHA3 hashes, it | |
| 148 | 149 | never actually generates any SHA3 hashes. |
| 149 | 150 | |
| 150 | -Beginning with Fossil 2.1, the default hash policy for legacy repositories | |
| 151 | -changed to "auto". | |
| 152 | -That means Fossil 2.1 will continue to generate only SHA1 hashes until it | |
| 153 | -encounters one artifact with a SHA3 hash. Once a single SHA3 hash is | |
| 154 | -seen, Fossil automatically switches to "sha3" mode and thereafter generates | |
| 151 | +From Fossil 2.1 through 2.9, the default hash policy for legacy repositories | |
| 152 | +changed to "auto", meaning that | |
| 153 | +Fossil continued to generate only SHA1 hashes until it | |
| 154 | +encountered one artifact with a SHA3 hash. Once those older versions of | |
| 155 | +Fossil saw a single SHA3 hash, they | |
| 156 | +automatically switched to "sha3" mode and thereafter generated | |
| 155 | 157 | only SHA3 hashes. |
| 156 | 158 | |
| 157 | 159 | When a new repository is created by cloning, the hash policy is copied |
| 158 | 160 | from the parent. |
| 159 | 161 | |
| @@ -162,39 +164,36 @@ | ||
| 162 | 164 | That means new repositories |
| 163 | 165 | will normally hold nothing except SHA3 hashes. The hash policy for new |
| 164 | 166 | repositories can be overridden using the "--sha1" option to the |
| 165 | 167 | "fossil new" command. |
| 166 | 168 | |
| 167 | -Even after upgrading to Fossil 2.1, Fossil will continue to use nothing | |
| 168 | -but SHA1 hashes on legacy repositories, thus preserving complete | |
| 169 | -compatibility with Fossil 1.37 and before. If you want Fossil to go | |
| 169 | +If you are still on Fossil 2.1 through 2.9 but you want Fossil to go | |
| 170 | 170 | ahead and start using SHA3 hashes, change the hash policy to |
| 171 | 171 | "sha3" using a command like this: |
| 172 | 172 | |
| 173 | 173 | <blockquote><verbatim> |
| 174 | 174 | fossil hash-policy sha3 |
| 175 | 175 | </verbatim></blockquote> |
| 176 | 176 | |
| 177 | -The next check-in will use a SHA3 hash. And when that check-in is pushed | |
| 178 | -to colleagues, their copies of Fossil will see the new SHA3-named artifact | |
| 179 | -and automatically convert to SHA3 as well. | |
| 177 | +The next check-in will use a SHA3 hash, so that when that check-in is pushed | |
| 178 | +to colleagues, their clones will include the new SHA3-named artifact, so | |
| 179 | +their local Fossil instances will automatically convert their clones to | |
| 180 | +"sha3" mode as well. | |
| 180 | 181 | |
| 181 | 182 | Of course, if some members of your team stubbornly refuse to upgrade past |
| 182 | 183 | Fossil 1.37, you should avoid changing the hash policy and creating |
| 183 | 184 | artifacts with SHA3 names, because once you do that your recalcitrant |
| 184 | 185 | coworkers will no longer be able to collaborate. |
| 185 | 186 | |
| 186 | 187 | <h2>A Pure SHA3 Future</h2> |
| 187 | 188 | |
| 188 | -Fossil 2.10 changed the default hash policy to "sha3" mode. So if you | |
| 189 | +Fossil 2.10 changed the default hash policy to "sha3" mode even for | |
| 190 | +legacy repositories, so if you | |
| 189 | 191 | upgrade to the latest version of Fossil, all of your new artifacts will |
| 190 | 192 | use a SHA3 hash. Legacy SHA1 artifacts continue to use their original |
| 191 | -names but new artifacts will use SHA3 names. | |
| 193 | +names, but new artifacts will use SHA3 names. You might not even notice | |
| 194 | +this automatic change over to stronger hashes. | |
| 192 | 195 | |
| 193 | -We decided to make the change pure SHA3 since the last known distributor | |
| 196 | +We decided to make the change to pure SHA3 since the last known distributor | |
| 194 | 197 | of Fossil 1.x binaries — Debian 9 — was finally replaced in June 2019 |
| 195 | -by a newer version distributing Fossil 2.x. All other known sources of | |
| 198 | +by Debian 10, which included Fossil 2.8. All other known sources of | |
| 196 | 199 | Fossil 1.x binaries upgraded well before that point. |
| 197 | - | |
| 198 | -Because Fossil 2.x tends to silently upgrade existing repos to SHA-3 | |
| 199 | -mode unless carefully forced not to, you probably won't even notice the | |
| 200 | -change. | |
| 201 | 200 |
| --- www/hashpolicy.wiki | |
| +++ www/hashpolicy.wiki | |
| @@ -13,12 +13,12 @@ | |
| 13 | * Legacy repositories will continue working just as |
| 14 | they always have, without any conversions or upgrades. |
| 15 | * Historical check-ins will keep their same historical |
| 16 | SHA1 names. |
| 17 | * New check-ins will get more secure SHA3-256 hash names. |
| 18 | * Your workflow will be unchanged. |
| 19 | * Everything will continue as if nothing happened. |
| 20 | |
| 21 | But if you are curious and want a deeper understanding of what is |
| 22 | going on, read on... |
| 23 | |
| 24 | |
| @@ -85,13 +85,13 @@ | |
| 85 | To be clear: Fossil (version 2.0 and later) |
| 86 | allows the SHA1 and SHA3 hashes to be mixed within |
| 87 | the same repository. Older check-ins, created years ago, |
| 88 | continue to be named using their legacy SHA1 hashes while |
| 89 | newer check-ins are named using modern SHA3 hashes. There |
| 90 | is not need to "convert" a repository from SHA1 over to SHA3. |
| 91 | You can see this in Fossil itself. The recent |
| 92 | [9d9ef82234f63758] check-in uses a SHA3 hash where as the older |
| 93 | [1669115ab9d05c18] check-in uses a SHA1 hash. |
| 94 | |
| 95 | Other than permitting the use of SHA3 in addition to SHA1, there |
| 96 | were no file format changes in Fossil version 2.0 relative |
| 97 | to the previous version 1.37. Both Fossil 2.0 and Fossil 1.37 read |
| @@ -112,11 +112,11 @@ | |
| 112 | <td valign='top'>sha1</td> |
| 113 | <td>Name all new artifacts using the (Hardened) SHA1 hash algorithm.</td> |
| 114 | </tr> |
| 115 | <tr> |
| 116 | <td valign='top'>auto</td> |
| 117 | <td>Name new artifacts using the SHA1 hash algorithm. But if any |
| 118 | artifacts are encountered which are already named using SHA3, then |
| 119 | automatically switch the hash policy to "sha3"</td> |
| 120 | </tr> |
| 121 | <tr> |
| 122 | <td valign='top'>sha3</td> |
| @@ -128,11 +128,11 @@ | |
| 128 | <tr> |
| 129 | <td valign='top'>sha3-only</td> |
| 130 | <td>Name new artifacts using the SHA3 hash algorithm even if the artifact |
| 131 | already has a SHA1 name. In other words, force the use of SHA3. This can |
| 132 | cause some artifacts to be added to the repository twice, once under their |
| 133 | SHA1 name and again under their SHA3 name. But delta compression will |
| 134 | prevent that from causing repository size problems.</td> |
| 135 | </tr> |
| 136 | <tr> |
| 137 | <td valign='top'>shun-sha1</td> |
| 138 | <td>Like "sha3-only" but at this level do not accept a push of SHA1-named |
| @@ -140,20 +140,22 @@ | |
| 140 | that artifact is discarded and ignored. |
| 141 | </tr> |
| 142 | </table> |
| 143 | |
| 144 | For Fossil 2.0, and obviously also for Fossil 1.37 and before, the |
| 145 | only hash policy supported was "sha1". All new artifacts were named |
| 146 | using their SHA1 hash. |
| 147 | Even though Fossil 2.0 was capable of understanding SHA3 hashes, it |
| 148 | never actually generates any SHA3 hashes. |
| 149 | |
| 150 | Beginning with Fossil 2.1, the default hash policy for legacy repositories |
| 151 | changed to "auto". |
| 152 | That means Fossil 2.1 will continue to generate only SHA1 hashes until it |
| 153 | encounters one artifact with a SHA3 hash. Once a single SHA3 hash is |
| 154 | seen, Fossil automatically switches to "sha3" mode and thereafter generates |
| 155 | only SHA3 hashes. |
| 156 | |
| 157 | When a new repository is created by cloning, the hash policy is copied |
| 158 | from the parent. |
| 159 | |
| @@ -162,39 +164,36 @@ | |
| 162 | That means new repositories |
| 163 | will normally hold nothing except SHA3 hashes. The hash policy for new |
| 164 | repositories can be overridden using the "--sha1" option to the |
| 165 | "fossil new" command. |
| 166 | |
| 167 | Even after upgrading to Fossil 2.1, Fossil will continue to use nothing |
| 168 | but SHA1 hashes on legacy repositories, thus preserving complete |
| 169 | compatibility with Fossil 1.37 and before. If you want Fossil to go |
| 170 | ahead and start using SHA3 hashes, change the hash policy to |
| 171 | "sha3" using a command like this: |
| 172 | |
| 173 | <blockquote><verbatim> |
| 174 | fossil hash-policy sha3 |
| 175 | </verbatim></blockquote> |
| 176 | |
| 177 | The next check-in will use a SHA3 hash. And when that check-in is pushed |
| 178 | to colleagues, their copies of Fossil will see the new SHA3-named artifact |
| 179 | and automatically convert to SHA3 as well. |
| 180 | |
| 181 | Of course, if some members of your team stubbornly refuse to upgrade past |
| 182 | Fossil 1.37, you should avoid changing the hash policy and creating |
| 183 | artifacts with SHA3 names, because once you do that your recalcitrant |
| 184 | coworkers will no longer be able to collaborate. |
| 185 | |
| 186 | <h2>A Pure SHA3 Future</h2> |
| 187 | |
| 188 | Fossil 2.10 changed the default hash policy to "sha3" mode. So if you |
| 189 | upgrade to the latest version of Fossil, all of your new artifacts will |
| 190 | use a SHA3 hash. Legacy SHA1 artifacts continue to use their original |
| 191 | names but new artifacts will use SHA3 names. |
| 192 | |
| 193 | We decided to make the change pure SHA3 since the last known distributor |
| 194 | of Fossil 1.x binaries — Debian 9 — was finally replaced in June 2019 |
| 195 | by a newer version distributing Fossil 2.x. All other known sources of |
| 196 | Fossil 1.x binaries upgraded well before that point. |
| 197 | |
| 198 | Because Fossil 2.x tends to silently upgrade existing repos to SHA-3 |
| 199 | mode unless carefully forced not to, you probably won't even notice the |
| 200 | change. |
| 201 |
| --- www/hashpolicy.wiki | |
| +++ www/hashpolicy.wiki | |
| @@ -13,12 +13,12 @@ | |
| 13 | * Legacy repositories will continue working just as |
| 14 | they always have, without any conversions or upgrades. |
| 15 | * Historical check-ins will keep their same historical |
| 16 | SHA1 names. |
| 17 | * New check-ins will get more secure SHA3-256 hash names. |
| 18 | * Everything will continue as if nothing happened. |
| 19 | * Your workflow will be unchanged. |
| 20 | |
| 21 | But if you are curious and want a deeper understanding of what is |
| 22 | going on, read on... |
| 23 | |
| 24 | |
| @@ -85,13 +85,13 @@ | |
| 85 | To be clear: Fossil (version 2.0 and later) |
| 86 | allows the SHA1 and SHA3 hashes to be mixed within |
| 87 | the same repository. Older check-ins, created years ago, |
| 88 | continue to be named using their legacy SHA1 hashes while |
| 89 | newer check-ins are named using modern SHA3 hashes. There |
| 90 | is no need to "convert" a repository from SHA1 over to SHA3. |
| 91 | You can see this in Fossil itself. The recent |
| 92 | [9d9ef82234f63758] check-in uses a SHA3 hash whereas the older |
| 93 | [1669115ab9d05c18] check-in uses a SHA1 hash. |
| 94 | |
| 95 | Other than permitting the use of SHA3 in addition to SHA1, there |
| 96 | were no file format changes in Fossil version 2.0 relative |
| 97 | to the previous version 1.37. Both Fossil 2.0 and Fossil 1.37 read |
| @@ -112,11 +112,11 @@ | |
| 112 | <td valign='top'>sha1</td> |
| 113 | <td>Name all new artifacts using the (Hardened) SHA1 hash algorithm.</td> |
| 114 | </tr> |
| 115 | <tr> |
| 116 | <td valign='top'>auto</td> |
| 117 | <td>Name new artifacts using the SHA1 hash algorithm, but if any |
| 118 | artifacts are encountered which are already named using SHA3, then |
| 119 | automatically switch the hash policy to "sha3"</td> |
| 120 | </tr> |
| 121 | <tr> |
| 122 | <td valign='top'>sha3</td> |
| @@ -128,11 +128,11 @@ | |
| 128 | <tr> |
| 129 | <td valign='top'>sha3-only</td> |
| 130 | <td>Name new artifacts using the SHA3 hash algorithm even if the artifact |
| 131 | already has a SHA1 name. In other words, force the use of SHA3. This can |
| 132 | cause some artifacts to be added to the repository twice, once under their |
| 133 | SHA1 name and again under their SHA3 name, but delta compression will |
| 134 | prevent that from causing repository size problems.</td> |
| 135 | </tr> |
| 136 | <tr> |
| 137 | <td valign='top'>shun-sha1</td> |
| 138 | <td>Like "sha3-only" but at this level do not accept a push of SHA1-named |
| @@ -140,20 +140,22 @@ | |
| 140 | that artifact is discarded and ignored. |
| 141 | </tr> |
| 142 | </table> |
| 143 | |
| 144 | For Fossil 2.0, and obviously also for Fossil 1.37 and before, the |
| 145 | only hash policy supported was the one now called "sha1", meaning that |
| 146 | all new artifacts were named |
| 147 | using a SHA1 hash. |
| 148 | Even though Fossil 2.0 added the capability of understanding SHA3 hashes, it |
| 149 | never actually generates any SHA3 hashes. |
| 150 | |
| 151 | From Fossil 2.1 through 2.9, the default hash policy for legacy repositories |
| 152 | changed to "auto", meaning that |
| 153 | Fossil continued to generate only SHA1 hashes until it |
| 154 | encountered one artifact with a SHA3 hash. Once those older versions of |
| 155 | Fossil saw a single SHA3 hash, they |
| 156 | automatically switched to "sha3" mode and thereafter generated |
| 157 | only SHA3 hashes. |
| 158 | |
| 159 | When a new repository is created by cloning, the hash policy is copied |
| 160 | from the parent. |
| 161 | |
| @@ -162,39 +164,36 @@ | |
| 164 | That means new repositories |
| 165 | will normally hold nothing except SHA3 hashes. The hash policy for new |
| 166 | repositories can be overridden using the "--sha1" option to the |
| 167 | "fossil new" command. |
| 168 | |
| 169 | If you are still on Fossil 2.1 through 2.9 but you want Fossil to go |
| 170 | ahead and start using SHA3 hashes, change the hash policy to |
| 171 | "sha3" using a command like this: |
| 172 | |
| 173 | <blockquote><verbatim> |
| 174 | fossil hash-policy sha3 |
| 175 | </verbatim></blockquote> |
| 176 | |
| 177 | The next check-in will use a SHA3 hash, so that when that check-in is pushed |
| 178 | to colleagues, their clones will include the new SHA3-named artifact, so |
| 179 | their local Fossil instances will automatically convert their clones to |
| 180 | "sha3" mode as well. |
| 181 | |
| 182 | Of course, if some members of your team stubbornly refuse to upgrade past |
| 183 | Fossil 1.37, you should avoid changing the hash policy and creating |
| 184 | artifacts with SHA3 names, because once you do that your recalcitrant |
| 185 | coworkers will no longer be able to collaborate. |
| 186 | |
| 187 | <h2>A Pure SHA3 Future</h2> |
| 188 | |
| 189 | Fossil 2.10 changed the default hash policy to "sha3" mode even for |
| 190 | legacy repositories, so if you |
| 191 | upgrade to the latest version of Fossil, all of your new artifacts will |
| 192 | use a SHA3 hash. Legacy SHA1 artifacts continue to use their original |
| 193 | names, but new artifacts will use SHA3 names. You might not even notice |
| 194 | this automatic change over to stronger hashes. |
| 195 | |
| 196 | We decided to make the change to pure SHA3 since the last known distributor |
| 197 | of Fossil 1.x binaries — Debian 9 — was finally replaced in June 2019 |
| 198 | by Debian 10, which included Fossil 2.8. All other known sources of |
| 199 | Fossil 1.x binaries upgraded well before that point. |
| 200 |