Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-04-23 14:21:11 -0400
committerMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-05-04 10:39:46 -0400
commit97873b618d045811bcb15ecc1454d2db0fe32fa5 (patch)
tree3509b6d087ae9d2ac22b735c48ca67ba2e6fba48 /doc
parent4ce7ba754517d8b8ad2688a8069c1f17f9f0e513 (diff)
downloadliza-97873b618d045811bcb15ecc1454d2db0fe32fa5.tar.gz
liza-97873b618d045811bcb15ecc1454d2db0fe32fa5.tar.bz2
liza-97873b618d045811bcb15ecc1454d2db0fe32fa5.zip
doc: Add information on JS libraries used
* doc/hacking.texi: New file with information on libraries. * doc/liza.texi: Include it. Add to menu.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/hacking.texi107
-rw-r--r--doc/liza.texi6
3 files changed, 112 insertions, 3 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index d7e8b35..40fe68c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -24,7 +24,7 @@ info_TEXINFOS = liza.texi
liza_TEXINFOS = license.texi macros.texi config.texi liza.css \
design.texi assert.texi bucket.texi client.texi \
dapi.texi pred.texi program.texi server.texi \
- validation.texi \
+ validation.texi hacking.texi \
diagram/event-graph.svg
diagram/%.svg: diagram/%.dot
diff --git a/doc/hacking.texi b/doc/hacking.texi
new file mode 100644
index 0000000..c64a2ed
--- /dev/null
+++ b/doc/hacking.texi
@@ -0,0 +1,107 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2018 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Hacking
+@chapter Hacking Liza
+@helpwanted
+This chapter provides general information and guidance for
+ [prospective] developers of Liza.
+
+@dnindex Libraries
+@dnindex GNU ease.js
+@dnindex Mocha
+@dnindex Chai
+For writing classes; interfaces; and traits,
+ developers should familiarize themselves with
+ @url{https://gnu.org/software/easejs,GNU ease.js}.
+For writing unit tests,
+ developers should be familiarize themselves with
+ @url{https://mochajs.org/,Mocha} and
+ @url{http://www.chaijs.com/,Chai}.
+For more information on the libraries used by Liza,
+ see @ref{Libraries}.
+
+@menu
+* Libraries:: The few libraries used by Liza
+@end menu
+
+
+@node Libraries
+@section Libraries Used
+@dnindex Libraries
+Liza does not use many libraries.
+The primary reason for this was that few libraries useful to Liza
+ existed during its initial development@mdash{
+ }Node.js and its community was still very young.
+With that said,
+ care should be taken to ensure that libraries are added only after a
+ careful analysis of its costs and benefits,
+ as they add volatility to the whole system and may also
+ introduce security vulnerabilities outside of our control.
+They further introduce maintenance obligations for keeping up with
+ newer versions of those libraries and addressing
+ backwards-compatibility concerns.
+
+
+@subsection System Libraries
+@dnindex ease.js, GNU
+JavaScript does not natively support the classical object-oriented
+ model familiar to users of more traditional classical
+ object-oriented languages like Java, C++, C#, and@tie{}PHP.
+Liza is built using @url{https://gnu.org/software/easejs,GNU ease.js},
+ which provides those familiar features.
+The primary language used by developers in the office that created
+ Liza is@tie{}PHP,
+ which motivated the creation of ease.js to ease the burden of
+ entry.
+
+Consequently,
+ Liza is written in a classical object-oriented style rather than
+ using prototypes.
+The @code{class} keyword introduced in ECMAScript@tie{} is largely
+ syntatic sugar around the prototype model and does not address the
+ primary concerns of ease.js,
+ nor does it provide traits.
+
+
+@subsection Testing Libraries
+@dnindex Mocha
+@dnindex Chai
+@url{https://mochajs.org/,Mocha} is used as the test runner for
+ JavaScript unit tests.
+@url{http://www.chaijs.com/,Chai} is the assertion library.
+This differs from PHP development where a single system (PHPUnit)
+ encompasses both of these needs.
+
+Chai offers a few different styles of assertions (``should'',
+ ``expect'', and ``assert'');
+ Liza uses @url{http://www.chaijs.com/guide/styles/#expect,``expect''}.
+
+
+@subsection UI Libraries
+@dnindex jQuery
+jQuery was used in the past,
+ but has been largely purged from the system (and continues to be
+ removed) due to strong performance issues.
+Further,
+ now that browser APIs have stabalized and Liza no longer needs to
+ support as far back as Internet Explorer@tie{}6,
+ the standard DOM APIs are more than sufficient.
+
+Liza instead provides its own UI and DOM abstractions
+ (@srcrefraw{src/ui}) that have been optimized for Liza's needs.
+
+There are modern frameworks that may overlap with the type of UI
+ operations that Liza performs,
+ as well as certain DOM optimizations that it performs;
+ however,
+ it is unlikely that such frameworks (e.g. React, Angular, Meteor)
+ will ever be integrated,
+ as the cost of doing so exceeds the marginal benefit.
diff --git a/doc/liza.texi b/doc/liza.texi
index c8bd87e..6541538 100644
--- a/doc/liza.texi
+++ b/doc/liza.texi
@@ -1,6 +1,6 @@
\input texinfo @c -*-texinfo-*-
@c This document is part of the Liza Data Collection Framework manual.
-@c Copyright (C) 2014 R-T Specialty, LLC.
+@c Copyright (C) 2014, 2017, 2018 R-T Specialty, LLC.
@c
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@@ -27,7 +27,7 @@
This manual is for the Liza Data Collection Framework, version
@value{VERSION}.
-Copyright @copyright{} 2014, 2017 R-T Specialty, LLC.
+Copyright @copyright{} 2014, 2017, 2018 R-T Specialty, LLC.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -84,6 +84,7 @@ Free Documentation License''.
* Program::
* Server::
* Validation::
+* Hacking:: Information for developers of Liza
* License:: Document License
* Concept Index::
@ifset DEVNOTES
@@ -105,6 +106,7 @@ Free Documentation License''.
@include program.texi
@include server.texi
@include validation.texi
+@include hacking.texi
@include license.texi
@node Concept Index