Fossil SCM
Added "Arguments Against JavaScript & Our Rebuttals" section to javascript.md, based on the similar section in this branch's new js-policy.md doc. It's nearly a rewrite, but all of the points remain.
Commit
1e3ee576b7a41a189505b4f98f600d35b92ac9b83d60e26a40b7281059893b7f
Parent
32ef4cfa2429b9f…
1 file changed
+136
-3
+136
-3
| --- www/javascript.md | ||
| +++ www/javascript.md | ||
| @@ -1,13 +1,13 @@ | ||
| 1 | 1 | # Use of JavaScript in Fossil |
| 2 | 2 | |
| 3 | -## Philosophy | |
| 3 | +## Philosophy & Policy | |
| 4 | 4 | |
| 5 | 5 | The Fossil development project’s policy is to use JavaScript where it |
| 6 | 6 | helps make its web UI better, but to offer graceful fallbacks wherever |
| 7 | 7 | practical. The intent is that the UI be usable with JavaScript entirely |
| 8 | -disabled. In every place where Fossil uses JavaScript, it is an | |
| 8 | +disabled. In every place where Fossil uses JavaScript, it is an | |
| 9 | 9 | enhancement to provided functionality, and there is always another way |
| 10 | 10 | to accomplish a given end without using JavaScript. |
| 11 | 11 | |
| 12 | 12 | This is not to say that Fossil’s fall-backs for such cases are always as |
| 13 | 13 | elegant and functional as a no-JS purist might wish. That is simply |
| @@ -18,11 +18,14 @@ | ||
| 18 | 18 | doesn’t get as much attention as some might want. We do [accept code |
| 19 | 19 | contributions][cg], and we are philosophically in favor of graceful |
| 20 | 20 | fall-backs, so you are welcome to appoint yourself the position of no-JS |
| 21 | 21 | czar for the Fossil project! |
| 22 | 22 | |
| 23 | -Evil is in actions, not in nouns, so we do not believe JavaScript *can* | |
| 23 | +We cover some of the common arguments against JavaScript | |
| 24 | +[below](#debate), with our rebuttals to them. | |
| 25 | + | |
| 26 | +Evil is in actions, not in nouns: we do not believe JavaScript *can* | |
| 24 | 27 | be evil. It is an active technology, but the actions that matter here |
| 25 | 28 | are those of writing the code and checking it into the Fossil project |
| 26 | 29 | repository. None of the JavaScript code in Fossil is evil, a fact we |
| 27 | 30 | enforce by being careful about who we give check-in rights on the |
| 28 | 31 | repository to and by policing what code does get contributed. The Fossil |
| @@ -113,10 +116,140 @@ | ||
| 113 | 116 | Fossil instances or into other web sites. |
| 114 | 117 | |
| 115 | 118 | There is some server-side event logging, but that is done entirely |
| 116 | 119 | without JavaScript, so it’s off-topic here. |
| 117 | 120 | |
| 121 | + | |
| 122 | +## <a id="debate"></a>Arguments Against JavaScript & Our Rebuttals | |
| 123 | + | |
| 124 | +There many common arguments against the use of JavaScript. Rather than | |
| 125 | +rehash these same arguments on the [forum][ffor], we distill the common | |
| 126 | +ones we’ve heard before and give our stock answers to them here: | |
| 127 | + | |
| 128 | +1. "**It increases the size of the page download.**" | |
| 129 | + | |
| 130 | + The heaviest such pages served by Fossil only have about 8 kB of | |
| 131 | + compressed JavaScript. (You have to go out of your way to get Fossil | |
| 132 | + to serve uncompressed pages.) This is negligible, even over very | |
| 133 | + slow data connnections. If you are still somehow on a 56 kbit/sec | |
| 134 | + analog telephone modem, this extra script code would download in | |
| 135 | + about a second. | |
| 136 | + | |
| 137 | + Most JavaScript-based Fossil pages use less JavaScript than that. | |
| 138 | + | |
| 139 | + Atop that, Fossil 2.12 adds new script delivery methods with | |
| 140 | + aggressive caching enabled so that typical page loads will skip | |
| 141 | + re-loading this content on subsequent loads. These features are | |
| 142 | + currently optional: you must either set the new [`fossil server | |
| 143 | + --jsmode` option][fsrv] or the corresponding `jsmode` control line | |
| 144 | + in your [`fossil cgi`][fcgi] script when setting up your | |
| 145 | + [Fossil server][fshome]. That done, Fossil’s JavaScript files will | |
| 146 | + load almost instantly from the browser’s cache after the initial | |
| 147 | + page load, rather than be re-transferred over the network. | |
| 148 | + | |
| 149 | + Between the improved caching and the fact that it’s quicker to | |
| 150 | + transfer a partial Ajax page load than reload the entire page, the | |
| 151 | + aggregate cost of such pages is typically *lower* than the older | |
| 152 | + methods based on HTTP POST with a full server round-trip. You can | |
| 153 | + expect to recover the cost of the initial page load in 1-2 | |
| 154 | + round-trips. If we were to double the amount of JavaScript code, the | |
| 155 | + payoff time would increase to 2-4 round-trips. | |
| 156 | + | |
| 157 | +2. "**JavaScript is slow.**" | |
| 158 | + | |
| 159 | + It *was*, before September 2008. Google's introduction of [their V8 | |
| 160 | + JavaScript engine][v8] taught the world that JavaScript need not be | |
| 161 | + slow. This competitive pressure caused the other common JavaScript | |
| 162 | + interpreters to either improve or be replaced by one of the engines | |
| 163 | + that did improve to approach V8’s speed. | |
| 164 | + | |
| 165 | + Nowadays JavaScript is, as a rule, astoundingly fast. As the world | |
| 166 | + continues to move more and more to web-based applications and | |
| 167 | + services, JavaScript engine developers have ample motivation to keep | |
| 168 | + their engines fast and competitive. | |
| 169 | + | |
| 170 | + Once the scripts are cached, Ajax based page updates are faster than | |
| 171 | + the alternative. | |
| 172 | + | |
| 173 | +3. "**JavaScript is insecure.**" | |
| 174 | + | |
| 175 | + JavaScript is historically associated with some nefarious uses, but | |
| 176 | + the question is not whether JavaScript is itself evil, it is whether | |
| 177 | + its *authors* are evil. *Every byte* of JavaScript code used within | |
| 178 | + the Fossil UI is: | |
| 179 | + | |
| 180 | + * ...written by the Fossil developers, vetted by their peers. | |
| 181 | + | |
| 182 | + * ...[open source][flic] and [available][fsrc] to be inspected, | |
| 183 | + audited, and changed by its users. | |
| 184 | + | |
| 185 | + * ...compiled directly into the `fossil` binary in a | |
| 186 | + non-obfuscated form during the build process, so there are no | |
| 187 | + third-party servers delivering mysterious, obfuscated JS code to | |
| 188 | + the user. | |
| 189 | + | |
| 190 | + C, Fossil's main implementation language, has been associated with | |
| 191 | + far more security problems than JavaScript, yet the apparent | |
| 192 | + alternative to reducing the amount of JavaScript in Fossil is to | |
| 193 | + increase the amount of C code. Does it not make sense to place as | |
| 194 | + much trust in Fossil’s JavaScript code as in its C code? | |
| 195 | + | |
| 196 | + Local administrators can [modify the repository’s skin][cskin] to | |
| 197 | + inject additional JavaScript code into pages served by their Fossil | |
| 198 | + server. A typical case is to add a syntax highlighter like | |
| 199 | + [Prism.js][pjs] or [highlightjs][hljs] to the local repository. At | |
| 200 | + that point, your trust concern is not with Fossil’s use of | |
| 201 | + JavaScript, but with your trust in that repository’s administrator. | |
| 202 | + | |
| 203 | + Fossil's [default content security policy][dcsp] (CSP) | |
| 204 | + prohibits execution of JavaScript code which is delivered from | |
| 205 | + anywhere but the Fossil server which delivers the page. A local | |
| 206 | + administrator can change this CSP, but again this comes down to a | |
| 207 | + matter of trust with the administrator, not with Fossil itself. | |
| 208 | + | |
| 209 | +4. "**Cross-browser compatibility is poor.**" | |
| 210 | + | |
| 211 | + It most certainly was in the first decade or so of JavaScript’s | |
| 212 | + lifetime, resulting in the creation of powerful libraries like | |
| 213 | + jQuery to patch over the incompatibilities. Over time, the need for | |
| 214 | + such libraries has dropped as browser vendors have fixed the | |
| 215 | + incompatibilities. Cross-browser JavaScript compatibility issues | |
| 216 | + which affect web developers are, by and large, a thing of the past. | |
| 217 | + | |
| 218 | +5. "**Fossil UI works fine without JavaScript.**" | |
| 219 | + | |
| 220 | + While this is true today, and we have no philosophical objection to | |
| 221 | + it remaining true, we do not intend to limit ourselves to only those | |
| 222 | + features that can be created without JavaScript. The mere | |
| 223 | + availability of alternatives is not a good justification for holding | |
| 224 | + back on notable improvements when they're within easy reach. | |
| 225 | + | |
| 226 | + The no-JS case is a [minority position](#stats), so those that want | |
| 227 | + Fossil to have no-JS alternatives and graceful fallbacks will need | |
| 228 | + to get involved with the development if they want this state of | |
| 229 | + affairs to continue. | |
| 230 | + | |
| 231 | +6. "**My browser doesn’t have a JavaScript interpreter.**" | |
| 232 | + | |
| 233 | + The Fossil open source project has no full-time developers, and only | |
| 234 | + a few of these part-timers are responsible for the bulk of the code | |
| 235 | + in Fossil. If you want Fossil to support such niche use cases, then | |
| 236 | + you will have to [get involved with its development][cg]; it’s | |
| 237 | + *your* uncommon itch. | |
| 238 | + | |
| 239 | +[cskin]: ./customskin.md | |
| 240 | +[dcsp]: ./defcsp.md | |
| 241 | +[fcgi]: /help?cmd=cgi | |
| 242 | +[ffor]: https://fossil-scm.org/forum/ | |
| 243 | +[flic]: /doc/trunk/COPYRIGHT-BSD2.txt | |
| 244 | +[fsrc]: https://fossil-scm.org/home/file/src | |
| 245 | +[fsrv]: /help?cmd=server | |
| 246 | +[fshome]: /doc/trunk/www/server/ | |
| 247 | +[hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca | |
| 248 | +[pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d | |
| 249 | +[v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) | |
| 250 | + | |
| 118 | 251 | |
| 119 | 252 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 120 | 253 | |
| 121 | 254 | The remainder of this document will explain how Fossil currently uses |
| 122 | 255 | JavaScript and what it does when these uses are blocked. |
| 123 | 256 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -1,13 +1,13 @@ | |
| 1 | # Use of JavaScript in Fossil |
| 2 | |
| 3 | ## Philosophy |
| 4 | |
| 5 | The Fossil development project’s policy is to use JavaScript where it |
| 6 | helps make its web UI better, but to offer graceful fallbacks wherever |
| 7 | practical. The intent is that the UI be usable with JavaScript entirely |
| 8 | disabled. In every place where Fossil uses JavaScript, it is an |
| 9 | enhancement to provided functionality, and there is always another way |
| 10 | to accomplish a given end without using JavaScript. |
| 11 | |
| 12 | This is not to say that Fossil’s fall-backs for such cases are always as |
| 13 | elegant and functional as a no-JS purist might wish. That is simply |
| @@ -18,11 +18,14 @@ | |
| 18 | doesn’t get as much attention as some might want. We do [accept code |
| 19 | contributions][cg], and we are philosophically in favor of graceful |
| 20 | fall-backs, so you are welcome to appoint yourself the position of no-JS |
| 21 | czar for the Fossil project! |
| 22 | |
| 23 | Evil is in actions, not in nouns, so we do not believe JavaScript *can* |
| 24 | be evil. It is an active technology, but the actions that matter here |
| 25 | are those of writing the code and checking it into the Fossil project |
| 26 | repository. None of the JavaScript code in Fossil is evil, a fact we |
| 27 | enforce by being careful about who we give check-in rights on the |
| 28 | repository to and by policing what code does get contributed. The Fossil |
| @@ -113,10 +116,140 @@ | |
| 113 | Fossil instances or into other web sites. |
| 114 | |
| 115 | There is some server-side event logging, but that is done entirely |
| 116 | without JavaScript, so it’s off-topic here. |
| 117 | |
| 118 | |
| 119 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 120 | |
| 121 | The remainder of this document will explain how Fossil currently uses |
| 122 | JavaScript and what it does when these uses are blocked. |
| 123 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -1,13 +1,13 @@ | |
| 1 | # Use of JavaScript in Fossil |
| 2 | |
| 3 | ## Philosophy & Policy |
| 4 | |
| 5 | The Fossil development project’s policy is to use JavaScript where it |
| 6 | helps make its web UI better, but to offer graceful fallbacks wherever |
| 7 | practical. The intent is that the UI be usable with JavaScript entirely |
| 8 | disabled. In every place where Fossil uses JavaScript, it is an |
| 9 | enhancement to provided functionality, and there is always another way |
| 10 | to accomplish a given end without using JavaScript. |
| 11 | |
| 12 | This is not to say that Fossil’s fall-backs for such cases are always as |
| 13 | elegant and functional as a no-JS purist might wish. That is simply |
| @@ -18,11 +18,14 @@ | |
| 18 | doesn’t get as much attention as some might want. We do [accept code |
| 19 | contributions][cg], and we are philosophically in favor of graceful |
| 20 | fall-backs, so you are welcome to appoint yourself the position of no-JS |
| 21 | czar for the Fossil project! |
| 22 | |
| 23 | We cover some of the common arguments against JavaScript |
| 24 | [below](#debate), with our rebuttals to them. |
| 25 | |
| 26 | Evil is in actions, not in nouns: we do not believe JavaScript *can* |
| 27 | be evil. It is an active technology, but the actions that matter here |
| 28 | are those of writing the code and checking it into the Fossil project |
| 29 | repository. None of the JavaScript code in Fossil is evil, a fact we |
| 30 | enforce by being careful about who we give check-in rights on the |
| 31 | repository to and by policing what code does get contributed. The Fossil |
| @@ -113,10 +116,140 @@ | |
| 116 | Fossil instances or into other web sites. |
| 117 | |
| 118 | There is some server-side event logging, but that is done entirely |
| 119 | without JavaScript, so it’s off-topic here. |
| 120 | |
| 121 | |
| 122 | ## <a id="debate"></a>Arguments Against JavaScript & Our Rebuttals |
| 123 | |
| 124 | There many common arguments against the use of JavaScript. Rather than |
| 125 | rehash these same arguments on the [forum][ffor], we distill the common |
| 126 | ones we’ve heard before and give our stock answers to them here: |
| 127 | |
| 128 | 1. "**It increases the size of the page download.**" |
| 129 | |
| 130 | The heaviest such pages served by Fossil only have about 8 kB of |
| 131 | compressed JavaScript. (You have to go out of your way to get Fossil |
| 132 | to serve uncompressed pages.) This is negligible, even over very |
| 133 | slow data connnections. If you are still somehow on a 56 kbit/sec |
| 134 | analog telephone modem, this extra script code would download in |
| 135 | about a second. |
| 136 | |
| 137 | Most JavaScript-based Fossil pages use less JavaScript than that. |
| 138 | |
| 139 | Atop that, Fossil 2.12 adds new script delivery methods with |
| 140 | aggressive caching enabled so that typical page loads will skip |
| 141 | re-loading this content on subsequent loads. These features are |
| 142 | currently optional: you must either set the new [`fossil server |
| 143 | --jsmode` option][fsrv] or the corresponding `jsmode` control line |
| 144 | in your [`fossil cgi`][fcgi] script when setting up your |
| 145 | [Fossil server][fshome]. That done, Fossil’s JavaScript files will |
| 146 | load almost instantly from the browser’s cache after the initial |
| 147 | page load, rather than be re-transferred over the network. |
| 148 | |
| 149 | Between the improved caching and the fact that it’s quicker to |
| 150 | transfer a partial Ajax page load than reload the entire page, the |
| 151 | aggregate cost of such pages is typically *lower* than the older |
| 152 | methods based on HTTP POST with a full server round-trip. You can |
| 153 | expect to recover the cost of the initial page load in 1-2 |
| 154 | round-trips. If we were to double the amount of JavaScript code, the |
| 155 | payoff time would increase to 2-4 round-trips. |
| 156 | |
| 157 | 2. "**JavaScript is slow.**" |
| 158 | |
| 159 | It *was*, before September 2008. Google's introduction of [their V8 |
| 160 | JavaScript engine][v8] taught the world that JavaScript need not be |
| 161 | slow. This competitive pressure caused the other common JavaScript |
| 162 | interpreters to either improve or be replaced by one of the engines |
| 163 | that did improve to approach V8’s speed. |
| 164 | |
| 165 | Nowadays JavaScript is, as a rule, astoundingly fast. As the world |
| 166 | continues to move more and more to web-based applications and |
| 167 | services, JavaScript engine developers have ample motivation to keep |
| 168 | their engines fast and competitive. |
| 169 | |
| 170 | Once the scripts are cached, Ajax based page updates are faster than |
| 171 | the alternative. |
| 172 | |
| 173 | 3. "**JavaScript is insecure.**" |
| 174 | |
| 175 | JavaScript is historically associated with some nefarious uses, but |
| 176 | the question is not whether JavaScript is itself evil, it is whether |
| 177 | its *authors* are evil. *Every byte* of JavaScript code used within |
| 178 | the Fossil UI is: |
| 179 | |
| 180 | * ...written by the Fossil developers, vetted by their peers. |
| 181 | |
| 182 | * ...[open source][flic] and [available][fsrc] to be inspected, |
| 183 | audited, and changed by its users. |
| 184 | |
| 185 | * ...compiled directly into the `fossil` binary in a |
| 186 | non-obfuscated form during the build process, so there are no |
| 187 | third-party servers delivering mysterious, obfuscated JS code to |
| 188 | the user. |
| 189 | |
| 190 | C, Fossil's main implementation language, has been associated with |
| 191 | far more security problems than JavaScript, yet the apparent |
| 192 | alternative to reducing the amount of JavaScript in Fossil is to |
| 193 | increase the amount of C code. Does it not make sense to place as |
| 194 | much trust in Fossil’s JavaScript code as in its C code? |
| 195 | |
| 196 | Local administrators can [modify the repository’s skin][cskin] to |
| 197 | inject additional JavaScript code into pages served by their Fossil |
| 198 | server. A typical case is to add a syntax highlighter like |
| 199 | [Prism.js][pjs] or [highlightjs][hljs] to the local repository. At |
| 200 | that point, your trust concern is not with Fossil’s use of |
| 201 | JavaScript, but with your trust in that repository’s administrator. |
| 202 | |
| 203 | Fossil's [default content security policy][dcsp] (CSP) |
| 204 | prohibits execution of JavaScript code which is delivered from |
| 205 | anywhere but the Fossil server which delivers the page. A local |
| 206 | administrator can change this CSP, but again this comes down to a |
| 207 | matter of trust with the administrator, not with Fossil itself. |
| 208 | |
| 209 | 4. "**Cross-browser compatibility is poor.**" |
| 210 | |
| 211 | It most certainly was in the first decade or so of JavaScript’s |
| 212 | lifetime, resulting in the creation of powerful libraries like |
| 213 | jQuery to patch over the incompatibilities. Over time, the need for |
| 214 | such libraries has dropped as browser vendors have fixed the |
| 215 | incompatibilities. Cross-browser JavaScript compatibility issues |
| 216 | which affect web developers are, by and large, a thing of the past. |
| 217 | |
| 218 | 5. "**Fossil UI works fine without JavaScript.**" |
| 219 | |
| 220 | While this is true today, and we have no philosophical objection to |
| 221 | it remaining true, we do not intend to limit ourselves to only those |
| 222 | features that can be created without JavaScript. The mere |
| 223 | availability of alternatives is not a good justification for holding |
| 224 | back on notable improvements when they're within easy reach. |
| 225 | |
| 226 | The no-JS case is a [minority position](#stats), so those that want |
| 227 | Fossil to have no-JS alternatives and graceful fallbacks will need |
| 228 | to get involved with the development if they want this state of |
| 229 | affairs to continue. |
| 230 | |
| 231 | 6. "**My browser doesn’t have a JavaScript interpreter.**" |
| 232 | |
| 233 | The Fossil open source project has no full-time developers, and only |
| 234 | a few of these part-timers are responsible for the bulk of the code |
| 235 | in Fossil. If you want Fossil to support such niche use cases, then |
| 236 | you will have to [get involved with its development][cg]; it’s |
| 237 | *your* uncommon itch. |
| 238 | |
| 239 | [cskin]: ./customskin.md |
| 240 | [dcsp]: ./defcsp.md |
| 241 | [fcgi]: /help?cmd=cgi |
| 242 | [ffor]: https://fossil-scm.org/forum/ |
| 243 | [flic]: /doc/trunk/COPYRIGHT-BSD2.txt |
| 244 | [fsrc]: https://fossil-scm.org/home/file/src |
| 245 | [fsrv]: /help?cmd=server |
| 246 | [fshome]: /doc/trunk/www/server/ |
| 247 | [hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca |
| 248 | [pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d |
| 249 | [v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) |
| 250 | |
| 251 | |
| 252 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 253 | |
| 254 | The remainder of this document will explain how Fossil currently uses |
| 255 | JavaScript and what it does when these uses are blocked. |
| 256 |