Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--HACKING2
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/hacking.texi287
-rw-r--r--doc/liza.texi6
-rw-r--r--doc/macros.texi18
5 files changed, 312 insertions, 3 deletions
diff --git a/HACKING b/HACKING
index 41452f8..4ba212f 100644
--- a/HACKING
+++ b/HACKING
@@ -1,5 +1,7 @@
This project is developed internally at RT Specialty / LoVullo.
+For more information, see the section "Hacking Liza" in the manual.
+
Publishing New Versions
=======================
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..c498f42
--- /dev/null
+++ b/doc/hacking.texi
@@ -0,0 +1,287 @@
+@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 @easejs{}.
+For writing unit tests,
+ developers should be familiarize themselves with
+ @mocha{} and @chai{}.
+For more information on the libraries used by Liza,
+ see @ref{Libraries}.
+
+@dnindex Copyright Header
+@dnindex Source Files
+@dnindex Source File Naming
+Most source files have a general structure that must be followed.
+For example,
+ all such files must have a copyright header and
+ must be named after the class they define or system under test.
+For more information,
+ @pxref{Source Files}.
+
+Generally speaking,
+ developers should be familiar with vanilla ECMAScript;
+ DOM APIs;
+ and have a basic understanding of Node.js for well-rounded Liza
+ development.
+Writing this manual requires basic understanding of Texinfo.
+References for these topics and others are provided in
+ @pxref{Developer Resources}.
+
+@menu
+* Source Files:: Conventions for project files
+* Libraries:: The few libraries used by Liza
+* Developer Resources:: Where to look for more information
+@end menu
+
+
+@node Source Files
+@section Source Files
+@helpwanted
+
+@dnindex Source Files
+This section describes conventions for organizing files,
+ both in directory structure and in content.
+
+@menu
+* Copyright Header:: Important header at the top of all
+ source files
+* ECMAScript Strict Mode:Strict Mode. Always indicate strict mode
+@end menu
+
+@node Copyright Header
+@subsection Copyright Header
+@dnindex Copyright Header
+@dnindex License
+@dnindex GNU General Public License version 3
+@dnindex GNU General Public License version 3, Or Later
+Every source file should begin with a copyright header including the
+ appropriate years and license information.
+This ensures that this information is always available even if the
+ file becomes separated from the source distribution (e.g. is
+ distributed independently).
+Further,
+ it is necessary to indicate that the source file is distributed under
+ the GNU General Public License version@tie{}3 @emph{or later}@mdash{
+ }that ``or later'' clause does not exist as part of the license itself,
+ and so the mere presence of the license in @file{COPYING} is
+ insufficient.
+
+The copyright headers vary slightly between JavaScript and Texinfo
+ source files,
+ represented in @ref{f:cheader-js} and @ref{f:cheader-texi}
+ respectively.
+
+@float Figure, f:cheader-js
+@example
+/**
+ * DESCRIPTION OF FILE
+ *
+ * Copyright (C) 2017, 2018 R-T Specialty, LLC.
+ *
+ * This file is part of the Liza Data Collection Framework
+ *
+ * Liza is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+@end example
+@caption{Example copyright header for JavaScript files}
+@end float
+
+@float Figure, f:cheader-texi
+@example
+@@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''.
+@end example
+@caption{Example copyright header for JavaScript files}
+@end float
+
+For more information, see ``How to Apply These Terms to Your New
+ Programs'' under the @gplvthree{}.
+
+
+@node Strict Mode
+@subsection ECMAScript Strict Mode
+@dnindex Strict Mode, ECMAScript
+ECMAScript@tie{}5's
+ @url{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode,Strict Mode}
+ throws errors in more situations that may lead to buggy code,
+ allows for better optimization of ECMAScript code during runtime,
+ and prohibits syntax that conflicts with future ECMAScript versions.
+It also enables certain features,
+ like using @code{let} inside blocks.
+
+It should always be enabled going forward as shown in @ref{f:strict-mode}.
+The statement should immediately follow the copyright header
+ (@pxref{Copyright Header}),
+ before any other code.
+
+@float Figure, f:strict-mode
+@example
+// Copyright header
+
+'use strict';
+
+// ...
+@end example
+@caption{Enabling strict mode}
+@end float
+
+
+
+@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 GNU ease.js
+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 @easejs{},
+ 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
+@mocha{} is used as the test runner for JavaScript unit tests.
+@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.
+
+
+@node Developer Resources
+@section Developer Resources
+@dnindex Resources, Developer
+@dnindex MDN
+@url{https://developer.mozilla.org/en-US/docs/Web,MDN}@footnote{
+ Formerly the ``Mozilla Developer Network''; see
+ @url{https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/,''The Future of MDN: A Focus on Web Docs''}
+ for the history of the rename.}
+ is an essential resource for web development in general,
+ especially for JavaScript/ECMAScript and the various Web APIs.
+It contains resources for all levels,
+ including for those @url{https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps,unfamiliar with JavaScript}.
+All developers should familiarize themselves with the resources
+ available on MDN so that they understand what type of information is
+ readily accessible for future reference.
+
+@dnindex Node.js
+The Server (@pxref{Server}) uses Node.js.
+Although it's largely abstracted away,
+ there may be times where you need to touch on it,
+ in which case the
+ @url{https://nodejs.org/en/docs/,Node.js documentation} will be helpful.
+However,
+ it is important to note the version of Node.js that Liza is currently using,
+ as it may be woefully out of date and require looking at older
+ versions of the documentation.
+
+@dnindex Texinfo, GNU
+@cindex Documentation
+This manual is written using
+ @url{https://www.gnu.org/software/texinfo/,Texinfo},
+ which is the documentation format of the GNU@tie{}operating system.
+The format is structured and well-suited for software documentation
+ with output in a variety of formats.
+Looking at the source code of this manual will be helpful@mdash{
+ }it provides the general structure and numerous macros that are
+ specific to Liza.
+
+@dnindex MongoDB
+@cindex Database
+Data are persisted using @url{https://www.mongodb.com/,MongoDB}.
+Database operations in Liza are abstracted away,
+ but it's helpful to understand how to query the database directly to
+ understand how the system works and composes its data,
+ and for the purposes of debugging.
+
+For information on specific libraries used by Liza,
+ @pxref{Libraries}.
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
diff --git a/doc/macros.texi b/doc/macros.texi
index 53e9941..6d26fb0 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -248,3 +248,21 @@ See `\ref\' @proguicrefsuffix
@macro proguicrefsuffix{}
in the Liza Program@tie{}UI Compiler manual
@end macro
+
+
+@c common links
+@macro mocha{}
+@url{https://mochajs.org/,Mocha}
+@end macro
+
+@macro chai{}
+@url{http://www.chaijs.com/,Chai}
+@end macro
+
+@macro easejs{}
+@url{https://www.gnu.org/software/easejs,GNU ease.js}
+@end macro
+
+@macro gplvthree{}
+@url{https://www.gnu.org/licenses/gpl.html,GNU General Public License version@tie{}3}
+@end macro