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 . + */ +@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