Fossil SCM

Initial draft of a project policy doc explaining and justifying its use of JavaScript.

stephan 2020-08-19 08:00 UTC trunk
Commit 93e4561b0d56fe62e2c29552005823c43e5ab648a09f49c6bd57944a0317e258
Parent 7c98df415874259…
1 file changed +130
+ www/js-policy.md
A www/js-policy.md
+130
--- a/www/js-policy.md
+++ b/www/js-policy.md
@@ -0,0 +1,130 @@
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
17
+ 2020)n and justify how JS is used
18
+within the Fossil project.
19
+
20
+# Current Uses of JS in Fossil
21
+
22
+A brief summary of its current uses in this project:
23
+
24
+- To add qualify-of-life enhancements such as the ability to copy
25
+ artifact hashes to the system clipboard.
26
+
27
+- To provide asynchronous communication between the client and the
28
+ server, commonly known as "ajax" or "XHR" communication. This allows
29
+ certain pages to operate more quickly and fluidly by avoiding
30
+ complete round-trips to and from the server. Perhaps
31
+ counte-intuitively, the increased JS load such pages typically
32
+ require costs less bandwidth than is saved via using ajax traffic
33
+ instead of conventional HTML forms.
34
+
35
+- To implement, or reimplement, certain editing-centric features with
36
+ a degree of interactivity which is impossible to duplicate in purely
37
+ static pages. For example, the summer of 2020 saw the introduction
38
+ of [the /fileedit page](fileedit-page.md), which allows the editing,
39
+ in the browser, of SCM-controlled text files. Similarly, the wiki
40
+ editor was reimplemented to be JS-centric, improving the editing
41
+ capabilities enormously compared to the previously static form-based
42
+ interface.
43
+
44
+# Arguments Against JS and Rebuttals
45
+
46
+A brief summary of the common arguments *against* using JS, in no
47
+particular order, along with rebuttals against each of them:
48
+
49
+1. "It's increases the size of the page download."
50
+ - For the fossil pages which make heavy use of JS, the initial page
51
+ transfer size may increase: 6-8kb (compressed) is typical, and it
52
+ may even go up to a whopping 15kb (as of this writing, it's 8kb
53
+ compressed on our most JS-intensive page (`/fileedit`), and and unobfuscatterfaces is JS.
54
+
55
+The purpose of this document is to explain and justify how JS is used
56
+within the Fossil project.
57
+
58
+# Current Uses of JS in Fossil
59
+
60
+A brief summary of its current uses in this project:
61
+
62
+- To add qualify-of-life enhancements such as the ability to copy
63
+ artifact hashes to the system clipboard.
64
+
65
+- To provide asynchronous communication between the client and the
66
+ server, commonly known as "w. This allows
67
+ certain pages to operate more quickly and fluidly by avoiding
68
+ complete round-trips to and from the server. Perhaps
69
+ counter-intuitively, the increased JS load such pages typically
70
+ require costs less bandwidth than is saved via using ajax traffic
71
+ instead of conventional HTML forms.
72
+
73
+- To implement, or reimplement, certain editing-centric features with
74
+ a degree of interactivity which is impossible to duplicate in purely
75
+ static pages. For example, the summer of 2020 saw the introduction
76
+ of [the /fileedit page](fileedit-page.md), which allows the editing,
77
+ in the browser, of SCM-controlled text files. Similarly, the wiki
78
+ editor was reimplemented to be JS-centric, improving the editing
79
+ capabilities enormously compared to the previously static form-based
80
+ interface.
81
+
82
+# Arguments Against JS and Rebuttals
83
+
84
+A brief summary of the common arguments *against* using JS, in no
85
+particular order, along with rebuttals against each of them:
86
+
87
+1. "It's increases the size of the page download."
88
+ - For the fossil pages which make heavy use of JS, the initial page
89
+ transfer size may increase: 6-8kb (compressed) is typical, and it
90
+ may even go up to a whopping 15kb (as of this writing, it's 8kb
91
+ compressed on our most JS-intensive page (`/fileedit`), and only
92
+ 25kb uncom[of their
93
+ V8 JS engine][v8] taught the world that JS need not be slow, and
94
+ the JS engines used by every modern browser have been improved
95
+ upon by leaps and bounds to keep them competitive with Google's
96
+ engine. Nowadays JS is, as a rule, astoundingly fast. As the world
97
+ continues to move more and more to web-based applications
98
+ and services, JS engine developers have ample motivation to keep
99
+ their engines fast and competitive.
100
+
101
+[v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine)
102
+
103
+4. "Cross-browser compatibility is poor."
104
+ - It *most certainly was*. Starting around 2006/2007, when jQuery literally
105
+ revolutionized how people worked with and thought about JS, there
106
+ has been a massive industry-level push behind it and compatibility
107
+ has become the norm rather than the exception. Cross-browser JS
108
+ compatibility issues which affect web developers are, by and
109
+ large, a thing of the past.
110
+
111
+5. "The UI works fine without it."
112
+ - True, for *some* definition of "works." Modern times and modern
113
+ tools call for modern solutions. While we don't claim to be
114
+ cutting-edge technologists, the days of when static HTML
115
+ form-driven sites were the norm are long behind us. "It works
116
+ fine" is simply not a good justification for holding back on
117
+ notable improvements when they're within easy reach.
118
+
119
+6. "JS doesn't run in my text-mode browser."
120
+ - Frankly, neither do other most websites. A man goes to the doctor
121
+ and says, "doc, it hurts when I do this," and the doctor replies,
122
+ "then don't do that."
123
+
124
+
125
+In closing, the fossil developers want to see fossil *thrive*, and a
126
+small part of that is making it usable, and user-friendly, for a wider
127
+audience than the relatively small segment of users who would prefer
128
+that it remain completely static. Static forms were perfectly adequate
129
+for users in the 1990s, but modern users generally expect a smoother
130
+experience than that and modern developers generally want
--- a/www/js-policy.md
+++ b/www/js-policy.md
@@ -0,0 +1,130 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
--- a/www/js-policy.md
+++ b/www/js-policy.md
@@ -0,0 +1,130 @@
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
17 2020)n and justify how JS is used
18 within the Fossil project.
19
20 # Current Uses of JS in Fossil
21
22 A brief summary of its current uses in this project:
23
24 - To add qualify-of-life enhancements such as the ability to copy
25 artifact hashes to the system clipboard.
26
27 - To provide asynchronous communication between the client and the
28 server, commonly known as "ajax" or "XHR" communication. This allows
29 certain pages to operate more quickly and fluidly by avoiding
30 complete round-trips to and from the server. Perhaps
31 counte-intuitively, the increased JS load such pages typically
32 require costs less bandwidth than is saved via using ajax traffic
33 instead of conventional HTML forms.
34
35 - To implement, or reimplement, certain editing-centric features with
36 a degree of interactivity which is impossible to duplicate in purely
37 static pages. For example, the summer of 2020 saw the introduction
38 of [the /fileedit page](fileedit-page.md), which allows the editing,
39 in the browser, of SCM-controlled text files. Similarly, the wiki
40 editor was reimplemented to be JS-centric, improving the editing
41 capabilities enormously compared to the previously static form-based
42 interface.
43
44 # Arguments Against JS and Rebuttals
45
46 A brief summary of the common arguments *against* using JS, in no
47 particular order, along with rebuttals against each of them:
48
49 1. "It's increases the size of the page download."
50 - For the fossil pages which make heavy use of JS, the initial page
51 transfer size may increase: 6-8kb (compressed) is typical, and it
52 may even go up to a whopping 15kb (as of this writing, it's 8kb
53 compressed on our most JS-intensive page (`/fileedit`), and and unobfuscatterfaces is JS.
54
55 The purpose of this document is to explain and justify how JS is used
56 within the Fossil project.
57
58 # Current Uses of JS in Fossil
59
60 A brief summary of its current uses in this project:
61
62 - To add qualify-of-life enhancements such as the ability to copy
63 artifact hashes to the system clipboard.
64
65 - To provide asynchronous communication between the client and the
66 server, commonly known as "w. This allows
67 certain pages to operate more quickly and fluidly by avoiding
68 complete round-trips to and from the server. Perhaps
69 counter-intuitively, the increased JS load such pages typically
70 require costs less bandwidth than is saved via using ajax traffic
71 instead of conventional HTML forms.
72
73 - To implement, or reimplement, certain editing-centric features with
74 a degree of interactivity which is impossible to duplicate in purely
75 static pages. For example, the summer of 2020 saw the introduction
76 of [the /fileedit page](fileedit-page.md), which allows the editing,
77 in the browser, of SCM-controlled text files. Similarly, the wiki
78 editor was reimplemented to be JS-centric, improving the editing
79 capabilities enormously compared to the previously static form-based
80 interface.
81
82 # Arguments Against JS and Rebuttals
83
84 A brief summary of the common arguments *against* using JS, in no
85 particular order, along with rebuttals against each of them:
86
87 1. "It's increases the size of the page download."
88 - For the fossil pages which make heavy use of JS, the initial page
89 transfer size may increase: 6-8kb (compressed) is typical, and it
90 may even go up to a whopping 15kb (as of this writing, it's 8kb
91 compressed on our most JS-intensive page (`/fileedit`), and only
92 25kb uncom[of their
93 V8 JS engine][v8] taught the world that JS need not be slow, and
94 the JS engines used by every modern browser have been improved
95 upon by leaps and bounds to keep them competitive with Google's
96 engine. Nowadays JS is, as a rule, astoundingly fast. As the world
97 continues to move more and more to web-based applications
98 and services, JS engine developers have ample motivation to keep
99 their engines fast and competitive.
100
101 [v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine)
102
103 4. "Cross-browser compatibility is poor."
104 - It *most certainly was*. Starting around 2006/2007, when jQuery literally
105 revolutionized how people worked with and thought about JS, there
106 has been a massive industry-level push behind it and compatibility
107 has become the norm rather than the exception. Cross-browser JS
108 compatibility issues which affect web developers are, by and
109 large, a thing of the past.
110
111 5. "The UI works fine without it."
112 - True, for *some* definition of "works." Modern times and modern
113 tools call for modern solutions. While we don't claim to be
114 cutting-edge technologists, the days of when static HTML
115 form-driven sites were the norm are long behind us. "It works
116 fine" is simply not a good justification for holding back on
117 notable improvements when they're within easy reach.
118
119 6. "JS doesn't run in my text-mode browser."
120 - Frankly, neither do other most websites. A man goes to the doctor
121 and says, "doc, it hurts when I do this," and the doctor replies,
122 "then don't do that."
123
124
125 In closing, the fossil developers want to see fossil *thrive*, and a
126 small part of that is making it usable, and user-friendly, for a wider
127 audience than the relatively small segment of users who would prefer
128 that it remain completely static. Static forms were perfectly adequate
129 for users in the 1990s, but modern users generally expect a smoother
130 experience than that and modern developers generally want

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button