From 97873b618d045811bcb15ecc1454d2db0fe32fa5 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 23 Apr 2018 14:21:11 -0400 Subject: [PATCH 1/4] doc: Add information on JS libraries used * doc/hacking.texi: New file with information on libraries. * doc/liza.texi: Include it. Add to menu. --- doc/Makefile.am | 2 +- doc/hacking.texi | 107 +++++++++++++++++++++++++++++++++++++++++++++++ doc/liza.texi | 6 ++- 3 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 doc/hacking.texi 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 From b74aa64ae81d0982a0d84353dc444f6dd2d55c21 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 23 Apr 2018 14:23:09 -0400 Subject: [PATCH 2/4] HACKING: Add reference to 'Hacking Liza' section of manual * HACKING: Add reference. --- HACKING | 2 ++ 1 file changed, 2 insertions(+) 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 ======================= From f0a469944f68843a7b8347992cbac86b1c4cc319 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 23 Apr 2018 14:26:32 -0400 Subject: [PATCH 3/4] doc: Macros for common library references * doc/hacking.texi (Hacking): Use mocha, chai, easejs macros. * doc/macros.texi (mocha, chai, easejs): New macros. --- doc/hacking.texi | 13 +++++-------- doc/macros.texi | 14 ++++++++++++++ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/doc/hacking.texi b/doc/hacking.texi index c64a2ed..e99c820 100644 --- a/doc/hacking.texi +++ b/doc/hacking.texi @@ -19,12 +19,10 @@ This chapter provides general information and guidance for @dnindex Mocha @dnindex Chai For writing classes; interfaces; and traits, - developers should familiarize themselves with - @url{https://gnu.org/software/easejs,GNU ease.js}. + developers should familiarize themselves with @easejs{}. For writing unit tests, developers should be familiarize themselves with - @url{https://mochajs.org/,Mocha} and - @url{http://www.chaijs.com/,Chai}. + @mocha{} and @chai{}. For more information on the libraries used by Liza, see @ref{Libraries}. @@ -55,7 +53,7 @@ They further introduce maintenance obligations for keeping up with 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}, +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, @@ -74,9 +72,8 @@ The @code{class} keyword introduced in ECMAScript@tie{} is largely @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. +@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. diff --git a/doc/macros.texi b/doc/macros.texi index 53e9941..255dc8a 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -248,3 +248,17 @@ 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 From 514cad1575d61db69ae2f612c1e6e7466bfe1db7 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Fri, 4 May 2018 10:50:35 -0400 Subject: [PATCH 4/4] doc: Source files and developer resources * doc/hacking.texi: Added new sections to menu. (Source Files): New section. (Developer Resources): New section. * doc/macros.texi (mocha,chai,easejs,gplv3): New macros for common links. --- doc/hacking.texi | 187 ++++++++++++++++++++++++++++++++++++++++++++++- doc/macros.texi | 4 + 2 files changed, 189 insertions(+), 2 deletions(-) diff --git a/doc/hacking.texi b/doc/hacking.texi index e99c820..c498f42 100644 --- a/doc/hacking.texi +++ b/doc/hacking.texi @@ -11,6 +11,7 @@ @node Hacking @chapter Hacking Liza @helpwanted + This chapter provides general information and guidance for [prospective] developers of Liza. @@ -26,11 +27,143 @@ For writing unit tests, 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 -* Libraries:: The few libraries used by Liza +* 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 . + */ +@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 @@ -49,7 +182,7 @@ They further introduce maintenance obligations for keeping up with @subsection System Libraries -@dnindex ease.js, GNU +@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. @@ -102,3 +235,53 @@ There are modern frameworks that may overlap with the type of UI 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/macros.texi b/doc/macros.texi index 255dc8a..6d26fb0 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -262,3 +262,7 @@ in the Liza Program@tie{}UI Compiler manual @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