Fossil SCM
Merged the "Future Plans for JavaScript in Fossil" section of js-policy.md into javascript.md. This all but zeroes out the contents of the old doc, so I've removed it. Future changes go into javascript.md.
Commit
4ad0d9798e775e3378f5bbddc15bd20e719c8bd784075f74d98c67aa39c1c47a
Parent
7eef486cf4a80fc…
2 files changed
+46
-197
+46
| --- www/javascript.md | ||
| +++ www/javascript.md | ||
| @@ -278,10 +278,12 @@ | ||
| 278 | 278 | [fshome]: /doc/trunk/www/server/ |
| 279 | 279 | [hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca |
| 280 | 280 | [pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d |
| 281 | 281 | [v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) |
| 282 | 282 | |
| 283 | + | |
| 284 | +---- | |
| 283 | 285 | |
| 284 | 286 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 285 | 287 | |
| 286 | 288 | The remainder of this document will explain how Fossil currently uses |
| 287 | 289 | JavaScript and what it does when these uses are blocked. |
| @@ -538,5 +540,49 @@ | ||
| 538 | 540 | However, we are willing to study patches to make this better. For |
| 539 | 541 | example, the wall clock displays could include the page load time in the |
| 540 | 542 | dynamically generated HTML shipped from the remote Fossil server, so |
| 541 | 543 | that in the absence of JavaScript, you at least get the page generation |
| 542 | 544 | time, expressed in the server’s time zone. |
| 545 | + | |
| 546 | +---- | |
| 547 | + | |
| 548 | +## <a id="future"></a>Future Plans for JavaScript in Fossil | |
| 549 | + | |
| 550 | +As of mid-2020, the informal provisional plan is to increase the Fossil | |
| 551 | +UI's use of JavaScript considerably compared to its historically minimal | |
| 552 | +uses. To that end, a framework of Fossil-centric APIs is being developed | |
| 553 | +in conjunction with new features to consolidate Fossil's historical | |
| 554 | +hodge-podge of JavaScript snippets into a coherent code base. | |
| 555 | + | |
| 556 | +When deciding which features to port to JavaScript, the rules of thumb | |
| 557 | +for this ongoing effort are: | |
| 558 | + | |
| 559 | +- Pages which primarily display data (e.g. the timeline) will remain | |
| 560 | + largely static HTML with graceful fallbacks for all places they do | |
| 561 | + use JavaScript. Though JavaScript can be used effectively to power | |
| 562 | + all sorts of wonderful data presentation, Fossil currently doesn't | |
| 563 | + benefit greatly from doing so. We use JavaScript on these pages only | |
| 564 | + to improve their usability, not to define their primary operations. | |
| 565 | + | |
| 566 | +- Pages which act as editors of some sort (e.g. the `/info` page) are | |
| 567 | + prime candidates for getting the same treatment as the old wiki | |
| 568 | + editor: reimplemented from the ground up in JavaScript using Ajax | |
| 569 | + type techniques. Similarly, a JS-driven overhaul is planned for the | |
| 570 | + forum’s post editor. | |
| 571 | + | |
| 572 | +These are guidelines, not immutable requirements. Our development | |
| 573 | +direction is guided by our priorities: | |
| 574 | + | |
| 575 | +1) Features the developers themselves want to have and/or work on. | |
| 576 | + | |
| 577 | +2) Features end users request which catch the interest of one or more | |
| 578 | +developers, provided the developer(s) in question are in a position to | |
| 579 | +expend the effort. | |
| 580 | + | |
| 581 | +3) Features end users and co-contributors can convince a developer into | |
| 582 | +coding even when they really don't want to. 😉 | |
| 583 | + | |
| 584 | +In all of this, Fossil's project lead understandably has the final | |
| 585 | +say-so in whether any given feature indeed gets merged into the mainline | |
| 586 | +trunk. Development of any given feature, no matter how much effort was | |
| 587 | +involved, does not guaranty its eventual inclusion into the public | |
| 588 | +releases. | |
| 543 | 589 | |
| 544 | 590 | DELETED www/js-policy.md |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -278,10 +278,12 @@ | |
| 278 | [fshome]: /doc/trunk/www/server/ |
| 279 | [hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca |
| 280 | [pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d |
| 281 | [v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) |
| 282 | |
| 283 | |
| 284 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 285 | |
| 286 | The remainder of this document will explain how Fossil currently uses |
| 287 | JavaScript and what it does when these uses are blocked. |
| @@ -538,5 +540,49 @@ | |
| 538 | However, we are willing to study patches to make this better. For |
| 539 | example, the wall clock displays could include the page load time in the |
| 540 | dynamically generated HTML shipped from the remote Fossil server, so |
| 541 | that in the absence of JavaScript, you at least get the page generation |
| 542 | time, expressed in the server’s time zone. |
| 543 | |
| 544 | ELETED www/js-policy.md |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -278,10 +278,12 @@ | |
| 278 | [fshome]: /doc/trunk/www/server/ |
| 279 | [hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca |
| 280 | [pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d |
| 281 | [v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) |
| 282 | |
| 283 | |
| 284 | ---- |
| 285 | |
| 286 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 287 | |
| 288 | The remainder of this document will explain how Fossil currently uses |
| 289 | JavaScript and what it does when these uses are blocked. |
| @@ -538,5 +540,49 @@ | |
| 540 | However, we are willing to study patches to make this better. For |
| 541 | example, the wall clock displays could include the page load time in the |
| 542 | dynamically generated HTML shipped from the remote Fossil server, so |
| 543 | that in the absence of JavaScript, you at least get the page generation |
| 544 | time, expressed in the server’s time zone. |
| 545 | |
| 546 | ---- |
| 547 | |
| 548 | ## <a id="future"></a>Future Plans for JavaScript in Fossil |
| 549 | |
| 550 | As of mid-2020, the informal provisional plan is to increase the Fossil |
| 551 | UI's use of JavaScript considerably compared to its historically minimal |
| 552 | uses. To that end, a framework of Fossil-centric APIs is being developed |
| 553 | in conjunction with new features to consolidate Fossil's historical |
| 554 | hodge-podge of JavaScript snippets into a coherent code base. |
| 555 | |
| 556 | When deciding which features to port to JavaScript, the rules of thumb |
| 557 | for this ongoing effort are: |
| 558 | |
| 559 | - Pages which primarily display data (e.g. the timeline) will remain |
| 560 | largely static HTML with graceful fallbacks for all places they do |
| 561 | use JavaScript. Though JavaScript can be used effectively to power |
| 562 | all sorts of wonderful data presentation, Fossil currently doesn't |
| 563 | benefit greatly from doing so. We use JavaScript on these pages only |
| 564 | to improve their usability, not to define their primary operations. |
| 565 | |
| 566 | - Pages which act as editors of some sort (e.g. the `/info` page) are |
| 567 | prime candidates for getting the same treatment as the old wiki |
| 568 | editor: reimplemented from the ground up in JavaScript using Ajax |
| 569 | type techniques. Similarly, a JS-driven overhaul is planned for the |
| 570 | forum’s post editor. |
| 571 | |
| 572 | These are guidelines, not immutable requirements. Our development |
| 573 | direction is guided by our priorities: |
| 574 | |
| 575 | 1) Features the developers themselves want to have and/or work on. |
| 576 | |
| 577 | 2) Features end users request which catch the interest of one or more |
| 578 | developers, provided the developer(s) in question are in a position to |
| 579 | expend the effort. |
| 580 | |
| 581 | 3) Features end users and co-contributors can convince a developer into |
| 582 | coding even when they really don't want to. 😉 |
| 583 | |
| 584 | In all of this, Fossil's project lead understandably has the final |
| 585 | say-so in whether any given feature indeed gets merged into the mainline |
| 586 | trunk. Development of any given feature, no matter how much effort was |
| 587 | involved, does not guaranty its eventual inclusion into the public |
| 588 | releases. |
| 589 | |
| 590 | ELETED www/js-policy.md |
D
www/js-policy.md
-197
| --- a/www/js-policy.md | ||
| +++ b/www/js-policy.md | ||
| @@ -1,197 +0,0 @@ | ||
| 1 | -# Fossil JavaScript Policy | |
| 2 | - | |
| 3 | -# <span style='color: red'>THIS IS A DRAFT DOCUMENT.</span> | |
| 4 | - | |
| 5 | -<span style='color: red'>IT IS NOT, IN ITS | |
| 6 | -CURRENT STATE, TO BE UNDERSTOOD AS OFFICIAL PROJECT STANCE.</span> | |
| 7 | - | |
| 8 | -The topic of using ECMAScript (better known as JavaScript, abbreviated | |
| 9 | -JS) in fossil's UI has always been a mildly contentious point. On the | |
| 10 | -one hand, the site "can" get by fine with purely static HTML, and some | |
| 11 | -users consider that to be not only adequate, but preferable. On the | |
| 12 | -other, some level of client-side-only interactivity or UI enhancement | |
| 13 | -is often useful (some would say preferable), and the only option for | |
| 14 | -implementing such things in HTML-based interfaces is JS. | |
| 15 | - | |
| 16 | -The purpose of this document is to explain and justify how JS is used | |
| 17 | -within the Fossil project. | |
| 18 | - | |
| 19 | -# Current Uses of JS in Fossil | |
| 20 | - | |
| 21 | -A brief summary of its current uses in this project: | |
| 22 | - | |
| 23 | -- To add qualify-of-life enhancements such as the ability to copy | |
| 24 | - artifact hashes to the system clipboard. | |
| 25 | - | |
| 26 | -- To provide asynchronous communication between the client and the | |
| 27 | - server, commonly known as "ajax" or "XHR" communication. This allows | |
| 28 | - certain pages to operate more quickly and fluidly by avoiding | |
| 29 | - complete round-trips to and from the server. Perhaps | |
| 30 | - counter-intuitively, the increased JS load such pages typically | |
| 31 | - require costs less bandwidth than is saved via using ajax traffic | |
| 32 | - instead of conventional HTML forms. | |
| 33 | - | |
| 34 | -- To implement, or reimplement, certain editing-centric features with | |
| 35 | - a degree of interactivity which is impossible to duplicate in purely | |
| 36 | - static pages. For example, the summer of 2020 saw the introduction | |
| 37 | - of [the /fileedit page](fileedit-page.md), which allows the editing, | |
| 38 | - in the browser, of SCM-controlled text files. Similarly, the wiki | |
| 39 | - editor was reimplemented to be JS-centric, improving the editing | |
| 40 | - capabilities enormously compared to the previously static form-based | |
| 41 | - interface. | |
| 42 | - | |
| 43 | -# Arguments Against JS and Rebuttals | |
| 44 | - | |
| 45 | -A brief summary of the common arguments *against* using JS, in no | |
| 46 | -particular order, along with rebuttals against each of them: | |
| 47 | - | |
| 48 | -1. "It's increases the size of the page download." | |
| 49 | - - For the fossil pages which make heavy use of JS, the initial page | |
| 50 | - transfer size may increase: 6-8kb (compressed) is typical, and it | |
| 51 | - may even go up to a whopping 15kb (as of this writing, it's 8kb | |
| 52 | - compressed on our most JS-intensive page (`/fileedit`), and only | |
| 53 | - 25kb uncompressed). With fossil's newer (summer 2020) | |
| 54 | - JS delivery mechanism and etags-related caching | |
| 55 | - improvements, such JS can be served with a single HTTP request and | |
| 56 | - cached by browsers for up to a year. Additionally, most pages | |
| 57 | - which use that much JS also use comparitively lightweight ajax | |
| 58 | - communication to eliminate page reloads and enable data-loss-free | |
| 59 | - recovery in certain error cases which could lose client-side edits | |
| 60 | - in a non-JS-powered page. The end result is that the aggregate | |
| 61 | - cost of such pages is actually *lower* than their static | |
| 62 | - counterparts, and the total bytes of JS "overhead" is equal to | |
| 63 | - only 1-2 full round-trip requests of the equivalent static pages. | |
| 64 | - | |
| 65 | -2. "It's insecure." | |
| 66 | - - JS is historically associated with some nefarious uses, but that's | |
| 67 | - a clear case of "hate the game, not the player." (C, fossil's main | |
| 68 | - implementation language, has been associated with far more | |
| 69 | - security leaks and such than JS has, as have several other | |
| 70 | - programming languages.) *Every byte* of JS code used within the | |
| 71 | - fossil UI is either written by the fossil developers or closely | |
| 72 | - vetted by them, every byte of it is open source, and every byte of | |
| 73 | - it is compiled directly into the fossil binary, in a | |
| 74 | - non-obfuscated form, during the build process, so there are no | |
| 75 | - third-party servers delivering mysterious, obfuscated JS code to | |
| 76 | - the user unless an administrator specifically installs some in | |
| 77 | - [their repository's skin](customskin.md). Additionally, fossil's | |
| 78 | - [default CSP](defcsp.md) prohibits execution of JS code which is | |
| 79 | - delivered from anywhere but the fossil server which delivers the | |
| 80 | - page. | |
| 81 | - | |
| 82 | -3. "It's slow." | |
| 83 | - - It *was*, before September 2008. Google's introduction of [their | |
| 84 | - V8 JS engine][v8] taught the world that JS need not be slow, and | |
| 85 | - the JS engines used by every modern browser have been improved | |
| 86 | - upon by leaps and bounds to keep them competitive with Google's | |
| 87 | - engine. Nowadays JS is, as a rule, astoundingly fast. As the world | |
| 88 | - continues to move more and more to web-based applications | |
| 89 | - and services, JS engine developers have ample motivation to keep | |
| 90 | - their engines fast and competitive. | |
| 91 | - | |
| 92 | -[v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) | |
| 93 | - | |
| 94 | -4. "Cross-browser compatibility is poor." | |
| 95 | - - It *most certainly was*. Since 2006/2007, when jQuery literally | |
| 96 | - revolutionized how people worked with and thought about JS, there | |
| 97 | - has been a massive industry-level push behind it and compatibility | |
| 98 | - has become the norm rather than the exception. Cross-browser JS | |
| 99 | - compatibility issues which affect web developers are, by and | |
| 100 | - large, a thing of the past. | |
| 101 | - | |
| 102 | -5. "The UI works fine without it." | |
| 103 | - - True, for *some* definition of "works." Modern times and modern | |
| 104 | - tools call for modern solutions. While we don't claim to be | |
| 105 | - cutting-edge technologists, the days of when static HTML | |
| 106 | - form-driven sites were the norm are long behind us. "It works | |
| 107 | - fine" is simply not a good justification for holding back on | |
| 108 | - notable improvements when they're within easy reach. | |
| 109 | - | |
| 110 | -6. "JS doesn't run in my text-mode browser." | |
| 111 | - - Frankly, neither do other most websites. A man goes to the doctor | |
| 112 | - and says, "doc, it hurts when I do this," and the doctor replies, | |
| 113 | - "then don't do that." | |
| 114 | - | |
| 115 | - | |
| 116 | -In closing, the fossil developers want to see fossil *thrive*, and a | |
| 117 | -small part of that is making it usable, and user-friendly, for a wider | |
| 118 | -audience than the relatively small segment of users who would prefer | |
| 119 | -that it remain completely static. Static forms were perfectly adequate | |
| 120 | -for users in the 1990s, but modern users generally expect a smoother | |
| 121 | -experience than that and modern developers generally want to write | |
| 122 | -more interesting code than that. | |
| 123 | - | |
| 124 | -JS is *not* a perfect solution, but it's what we have and, frankly, | |
| 125 | -modern editions of the language work very well (though some of the | |
| 126 | -HTML DOM APIs are admittedly somewhat wonky, they are, with | |
| 127 | -vanishingly few exceptions, cross-browser compatible and fast). | |
| 128 | - | |
| 129 | - | |
| 130 | -# Compatibility Concerns | |
| 131 | - | |
| 132 | -We aim to remain relatively compatible with the largest portions of | |
| 133 | -the client-side browser base. We use only standards-defined JS code | |
| 134 | -constructs or constructs which are known to work in the overwhelmingly | |
| 135 | -vast majority of browsers going back at least approximately 5 | |
| 136 | -years. Features added to the language less than approximately 5 years | |
| 137 | -agom, or those which are still in flux in standards committees, are | |
| 138 | -avoided, as it historically takes at least 5 years for new features to | |
| 139 | -propagate through the various browsers and their users. ECMA6 | |
| 140 | -a.k.a. ES6 a.k.a. ECMAScript 2015 provides a feature-rich basis which | |
| 141 | -is more than adequate for our purposes. | |
| 142 | - | |
| 143 | -On a related note: a fantastic resource for guaging the availibility | |
| 144 | -of individual JS, HTML, and CSS features is | |
| 145 | -[caniuse.com](https://caniuse.com/). | |
| 146 | - | |
| 147 | - | |
| 148 | -# Future Plans for JS in Fossil | |
| 149 | - | |
| 150 | -As of mid-2020, the (very informal) proverbial plan is to increase the | |
| 151 | -fossil UI's use of JS *considerably* compared to its historically | |
| 152 | -minimal use of the language. To that end, a framework of | |
| 153 | -fossil-centric APIs is being developed in conjunction with new features, to | |
| 154 | -consolidate fossil's historical hodge-podge of JS snippets into a coherent | |
| 155 | -code base. | |
| 156 | - | |
| 157 | -When deciding which features to port to JS, the rules of thumb for | |
| 158 | -this ongoing effort are: | |
| 159 | - | |
| 160 | -- Pages which primarily display data, e.g. the timeline, will remain | |
| 161 | - largely static HTML. Though JS *can* be used effectively to power | |
| 162 | - all sorts of wonderful data presentation, fossil currently doesn't | |
| 163 | - benefit greatly from doing so, so "data-presentation pages" get by | |
| 164 | - with static HTML and maybe a smidgen of JS. e.g., the timeline's | |
| 165 | - graph is implemented in JS, as is table sorting on several pages, | |
| 166 | - but those are all "nice-to-haves" which improve the experience but | |
| 167 | - do not define it. | |
| 168 | - | |
| 169 | -- Pages which act as editors of some sort, e.g. wiki pages | |
| 170 | - (`/wikiedit`), files (`/fileedit`), and checkin information (via | |
| 171 | - `/info`), are prime candidates for reimplementing in JS, and the two | |
| 172 | - first examples in that list were fossil's first JS-centric pages: | |
| 173 | - `/fileedit` was implemented from the ground up in JS and `/wikiedit` | |
| 174 | - was reimplemented from a static form-driven app. Similarly, a | |
| 175 | - JS-driven overhaul is planned for the forum, initially to add | |
| 176 | - JS-driven post editors (from there we'll see what | |
| 177 | - can/should/shouldn't be reimplemented in JS). | |
| 178 | - | |
| 179 | -Those are, however, simply guidelines, not immutable rules. Our | |
| 180 | -directions of development always boil down to, in order of general | |
| 181 | -priority: | |
| 182 | - | |
| 183 | -1) Features the developers themselves want to have and/or work | |
| 184 | -on. | |
| 185 | - | |
| 186 | -2) Features end users request which catch the interest of one or | |
| 187 | -more developers, provided the developer(s) in question are in a | |
| 188 | -position to expend the effort. | |
| 189 | - | |
| 190 | -3) Features end users and co-contributors can convince a developer | |
| 191 | -into coding even when they really don't want to ;). | |
| 192 | - | |
| 193 | -Even so, fossil's project lead understandably has the final say-so in | |
| 194 | -whether any given feature indeed gets merged into the mainline trunk, | |
| 195 | -so development of any given feature, no matter how much effort was | |
| 196 | -involved, does not guaranty its eventual inclusion into the public | |
| 197 | -releases. |
| --- a/www/js-policy.md | |
| +++ b/www/js-policy.md | |
| @@ -1,197 +0,0 @@ | |
| 1 | # Fossil JavaScript Policy |
| 2 | |
| 3 | # <span style='color: red'>THIS IS A DRAFT DOCUMENT.</span> |
| 4 | |
| 5 | <span style='color: red'>IT IS NOT, IN ITS |
| 6 | CURRENT STATE, TO BE UNDERSTOOD AS OFFICIAL PROJECT STANCE.</span> |
| 7 | |
| 8 | The topic of using ECMAScript (better known as JavaScript, abbreviated |
| 9 | JS) in fossil's UI has always been a mildly contentious point. On the |
| 10 | one hand, the site "can" get by fine with purely static HTML, and some |
| 11 | users consider that to be not only adequate, but preferable. On the |
| 12 | other, some level of client-side-only interactivity or UI enhancement |
| 13 | is often useful (some would say preferable), and the only option for |
| 14 | implementing such things in HTML-based interfaces is JS. |
| 15 | |
| 16 | The purpose of this document is to explain and justify how JS is used |
| 17 | within the Fossil project. |
| 18 | |
| 19 | # Current Uses of JS in Fossil |
| 20 | |
| 21 | A brief summary of its current uses in this project: |
| 22 | |
| 23 | - To add qualify-of-life enhancements such as the ability to copy |
| 24 | artifact hashes to the system clipboard. |
| 25 | |
| 26 | - To provide asynchronous communication between the client and the |
| 27 | server, commonly known as "ajax" or "XHR" communication. This allows |
| 28 | certain pages to operate more quickly and fluidly by avoiding |
| 29 | complete round-trips to and from the server. Perhaps |
| 30 | counter-intuitively, the increased JS load such pages typically |
| 31 | require costs less bandwidth than is saved via using ajax traffic |
| 32 | instead of conventional HTML forms. |
| 33 | |
| 34 | - To implement, or reimplement, certain editing-centric features with |
| 35 | a degree of interactivity which is impossible to duplicate in purely |
| 36 | static pages. For example, the summer of 2020 saw the introduction |
| 37 | of [the /fileedit page](fileedit-page.md), which allows the editing, |
| 38 | in the browser, of SCM-controlled text files. Similarly, the wiki |
| 39 | editor was reimplemented to be JS-centric, improving the editing |
| 40 | capabilities enormously compared to the previously static form-based |
| 41 | interface. |
| 42 | |
| 43 | # Arguments Against JS and Rebuttals |
| 44 | |
| 45 | A brief summary of the common arguments *against* using JS, in no |
| 46 | particular order, along with rebuttals against each of them: |
| 47 | |
| 48 | 1. "It's increases the size of the page download." |
| 49 | - For the fossil pages which make heavy use of JS, the initial page |
| 50 | transfer size may increase: 6-8kb (compressed) is typical, and it |
| 51 | may even go up to a whopping 15kb (as of this writing, it's 8kb |
| 52 | compressed on our most JS-intensive page (`/fileedit`), and only |
| 53 | 25kb uncompressed). With fossil's newer (summer 2020) |
| 54 | JS delivery mechanism and etags-related caching |
| 55 | improvements, such JS can be served with a single HTTP request and |
| 56 | cached by browsers for up to a year. Additionally, most pages |
| 57 | which use that much JS also use comparitively lightweight ajax |
| 58 | communication to eliminate page reloads and enable data-loss-free |
| 59 | recovery in certain error cases which could lose client-side edits |
| 60 | in a non-JS-powered page. The end result is that the aggregate |
| 61 | cost of such pages is actually *lower* than their static |
| 62 | counterparts, and the total bytes of JS "overhead" is equal to |
| 63 | only 1-2 full round-trip requests of the equivalent static pages. |
| 64 | |
| 65 | 2. "It's insecure." |
| 66 | - JS is historically associated with some nefarious uses, but that's |
| 67 | a clear case of "hate the game, not the player." (C, fossil's main |
| 68 | implementation language, has been associated with far more |
| 69 | security leaks and such than JS has, as have several other |
| 70 | programming languages.) *Every byte* of JS code used within the |
| 71 | fossil UI is either written by the fossil developers or closely |
| 72 | vetted by them, every byte of it is open source, and every byte of |
| 73 | it is compiled directly into the fossil binary, in a |
| 74 | non-obfuscated form, during the build process, so there are no |
| 75 | third-party servers delivering mysterious, obfuscated JS code to |
| 76 | the user unless an administrator specifically installs some in |
| 77 | [their repository's skin](customskin.md). Additionally, fossil's |
| 78 | [default CSP](defcsp.md) prohibits execution of JS code which is |
| 79 | delivered from anywhere but the fossil server which delivers the |
| 80 | page. |
| 81 | |
| 82 | 3. "It's slow." |
| 83 | - It *was*, before September 2008. Google's introduction of [their |
| 84 | V8 JS engine][v8] taught the world that JS need not be slow, and |
| 85 | the JS engines used by every modern browser have been improved |
| 86 | upon by leaps and bounds to keep them competitive with Google's |
| 87 | engine. Nowadays JS is, as a rule, astoundingly fast. As the world |
| 88 | continues to move more and more to web-based applications |
| 89 | and services, JS engine developers have ample motivation to keep |
| 90 | their engines fast and competitive. |
| 91 | |
| 92 | [v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) |
| 93 | |
| 94 | 4. "Cross-browser compatibility is poor." |
| 95 | - It *most certainly was*. Since 2006/2007, when jQuery literally |
| 96 | revolutionized how people worked with and thought about JS, there |
| 97 | has been a massive industry-level push behind it and compatibility |
| 98 | has become the norm rather than the exception. Cross-browser JS |
| 99 | compatibility issues which affect web developers are, by and |
| 100 | large, a thing of the past. |
| 101 | |
| 102 | 5. "The UI works fine without it." |
| 103 | - True, for *some* definition of "works." Modern times and modern |
| 104 | tools call for modern solutions. While we don't claim to be |
| 105 | cutting-edge technologists, the days of when static HTML |
| 106 | form-driven sites were the norm are long behind us. "It works |
| 107 | fine" is simply not a good justification for holding back on |
| 108 | notable improvements when they're within easy reach. |
| 109 | |
| 110 | 6. "JS doesn't run in my text-mode browser." |
| 111 | - Frankly, neither do other most websites. A man goes to the doctor |
| 112 | and says, "doc, it hurts when I do this," and the doctor replies, |
| 113 | "then don't do that." |
| 114 | |
| 115 | |
| 116 | In closing, the fossil developers want to see fossil *thrive*, and a |
| 117 | small part of that is making it usable, and user-friendly, for a wider |
| 118 | audience than the relatively small segment of users who would prefer |
| 119 | that it remain completely static. Static forms were perfectly adequate |
| 120 | for users in the 1990s, but modern users generally expect a smoother |
| 121 | experience than that and modern developers generally want to write |
| 122 | more interesting code than that. |
| 123 | |
| 124 | JS is *not* a perfect solution, but it's what we have and, frankly, |
| 125 | modern editions of the language work very well (though some of the |
| 126 | HTML DOM APIs are admittedly somewhat wonky, they are, with |
| 127 | vanishingly few exceptions, cross-browser compatible and fast). |
| 128 | |
| 129 | |
| 130 | # Compatibility Concerns |
| 131 | |
| 132 | We aim to remain relatively compatible with the largest portions of |
| 133 | the client-side browser base. We use only standards-defined JS code |
| 134 | constructs or constructs which are known to work in the overwhelmingly |
| 135 | vast majority of browsers going back at least approximately 5 |
| 136 | years. Features added to the language less than approximately 5 years |
| 137 | agom, or those which are still in flux in standards committees, are |
| 138 | avoided, as it historically takes at least 5 years for new features to |
| 139 | propagate through the various browsers and their users. ECMA6 |
| 140 | a.k.a. ES6 a.k.a. ECMAScript 2015 provides a feature-rich basis which |
| 141 | is more than adequate for our purposes. |
| 142 | |
| 143 | On a related note: a fantastic resource for guaging the availibility |
| 144 | of individual JS, HTML, and CSS features is |
| 145 | [caniuse.com](https://caniuse.com/). |
| 146 | |
| 147 | |
| 148 | # Future Plans for JS in Fossil |
| 149 | |
| 150 | As of mid-2020, the (very informal) proverbial plan is to increase the |
| 151 | fossil UI's use of JS *considerably* compared to its historically |
| 152 | minimal use of the language. To that end, a framework of |
| 153 | fossil-centric APIs is being developed in conjunction with new features, to |
| 154 | consolidate fossil's historical hodge-podge of JS snippets into a coherent |
| 155 | code base. |
| 156 | |
| 157 | When deciding which features to port to JS, the rules of thumb for |
| 158 | this ongoing effort are: |
| 159 | |
| 160 | - Pages which primarily display data, e.g. the timeline, will remain |
| 161 | largely static HTML. Though JS *can* be used effectively to power |
| 162 | all sorts of wonderful data presentation, fossil currently doesn't |
| 163 | benefit greatly from doing so, so "data-presentation pages" get by |
| 164 | with static HTML and maybe a smidgen of JS. e.g., the timeline's |
| 165 | graph is implemented in JS, as is table sorting on several pages, |
| 166 | but those are all "nice-to-haves" which improve the experience but |
| 167 | do not define it. |
| 168 | |
| 169 | - Pages which act as editors of some sort, e.g. wiki pages |
| 170 | (`/wikiedit`), files (`/fileedit`), and checkin information (via |
| 171 | `/info`), are prime candidates for reimplementing in JS, and the two |
| 172 | first examples in that list were fossil's first JS-centric pages: |
| 173 | `/fileedit` was implemented from the ground up in JS and `/wikiedit` |
| 174 | was reimplemented from a static form-driven app. Similarly, a |
| 175 | JS-driven overhaul is planned for the forum, initially to add |
| 176 | JS-driven post editors (from there we'll see what |
| 177 | can/should/shouldn't be reimplemented in JS). |
| 178 | |
| 179 | Those are, however, simply guidelines, not immutable rules. Our |
| 180 | directions of development always boil down to, in order of general |
| 181 | priority: |
| 182 | |
| 183 | 1) Features the developers themselves want to have and/or work |
| 184 | on. |
| 185 | |
| 186 | 2) Features end users request which catch the interest of one or |
| 187 | more developers, provided the developer(s) in question are in a |
| 188 | position to expend the effort. |
| 189 | |
| 190 | 3) Features end users and co-contributors can convince a developer |
| 191 | into coding even when they really don't want to ;). |
| 192 | |
| 193 | Even so, fossil's project lead understandably has the final say-so in |
| 194 | whether any given feature indeed gets merged into the mainline trunk, |
| 195 | so development of any given feature, no matter how much effort was |
| 196 | involved, does not guaranty its eventual inclusion into the public |
| 197 | releases. |
| --- a/www/js-policy.md | |
| +++ b/www/js-policy.md | |
| @@ -1,197 +0,0 @@ | |