Maestro Development

This articles gives an overview to Maestro development.

Areas of Development
Maestro development can be divided into three areas:


 * Maestro documentation - high-level Maestro Marketing and system architecture documentation, providing a high-level understanding of Maestro. Maestro documentation includes the Maestro Project web site, whitepapers, presentations, screencasts, etc.


 * Maestro system - the Maestro software itself, involving web applications incorporating a variety of technologies (e.g., PHP and the ATK framework, JavaScript, HTML, CSS, and SQL), but also involving Unix systems administration (e.g. shell scripts, LDAP, SSL, SASL, IMAP, MTA/MDA configuration, Apache, MySQL).


 * SCC (Swift Construction Company) - the documentation and operational data in the fictional Swift Construction Company's Maestro implementation. This includes the SCC Quality Management System, standard operating practice documents, SCC product documentation (e.g., part numbers, part drawing and specifications, assembly and test procedures), and SCC on-going operations data (e.g., project and employee timesheet data, manufactured serialized product data, purchasing and sales data, and general financial data).

Development Strategy
The Maestro development strategy consists of:


 * a development toolchain composed of free and open source software applications
 * code and documentation always kept under version control, including local development code
 * a Windows-based development workstation for compatability with enterprise IT environments and support resources
 * local unit testing on a virtualized clone of the production server
 * having a relatively simple environment but with broad capability



Development Toolchain

 * Web app stack. It is convenient on Windows to install a complete stack - typically consisting of the Apache web server, MySQL database server, and PHP server-side scripting engine. Some popular Windows-based stack bundles are:
 * XAMPP. The primary advantage of XAMPP is cross-platform support for Windows, Linux and Mac OS X.
 * AMPPS is for Windows only. Compared to XAMPP for Windows, AMPPS includes Python support, auto-update capability, and simple install of Softaculous apps (a collection of popular mostly-PHP web apps).
 * BitNami WAPPStack is for Windows only, and is one of several BitNami stacks that implement infrastructures only (e.g. Django, JBoss, Ruby, JRuby, Tomcat) or with web applications (e.g., KnowledgeTree, Alfresco, Drupal, SugarCRM). BitNami stacks are easily hosted on Amazon using the commercial BitNami Cloud Hosting service (an Amazon account is required). Compared to XAMPP for Windows, WAPPStack includes PostgreSQL and phpPgAdmin, and the Amazon AWS PHP SDK.
 * WampServer is for Windows only. Compared to XAMPP for Windows, the WampServer control icon easily switches access between the locahost and external access. WampServer has separate 32-bit and 64-bit versions.


 * LibreOffice (or OpenOffice.org) is used to author office-type documents. Documents are stored in their native format (also supported by current versions of Microsoft's office applications).
 * Impress is used for Maestro slide-show presentations
 * Calc is used to create product BOM files and export CSV format data for import into Maestro
 * Writer is used to author various Maestro and SCC text documents
 * Draw is used to create graphics used in various Maestro and SCC documents


 * The NetBeans IDE is used for coding PHP, JavaScript, HTML, CSS, and SQL, and for debugging PHP and JavaScript.


 * Git Extensions provides a GUI for the Git DVCS used by the Maestro project (includes Git command line apps, Git Bash shell, and KDiff3 for 3-way merging).


 * Oracle MySQL Workbench is used for MySQL database schema development and general adminstration, although phpMyAdmin is generally available on a Maestro server and is often adequate and more convenient to use.


 * Oracle VirtualBox provides a virtualized environment for hosting a local Unix-type test server (see How to build a virtual test server).


 * Microsoft Internet Explorer for interacting with Maestro (IE v8/9 is the standard for correct Maestro behavior). Mozilla Firefox is often preferred for development testing due to various plugins (FireBug for debugging CSS, HTML, and JavaScript, Web Developer for various developer related tools, and Molybdenum for testing). Depending on the environment, it may be desired to also test correct Maestro behavior with other browsers such as Apple Safari and Google Chrome.

The SCC Maestro implementation is also used for development, creating pages in the SCC Maestro KnowledgeBase, developing scenarios in the SCC Maestro ERP system, creating and managing issues in the SCC Maestro Issue Tracking system, etc.

The development strategy is based on using the Git Distributed Version Control System (DVCS) and hosting a virtual test server using VirtualBox.

Development Workstation
The documented development environment is based on workstations using Microsoft Windows due to its popularity with enterprises. However, Unix-like workstations are equally suitable (e.g., FreeBSD, PC-BSD, Apple OS X, and GNU Linux such as REL, Ubuntu, Linux Mint).

Virtual Test Server
A virtual server is hosted on the local workstation to duplicate the production server for final testing during Maestro development. See the How to build a virtual test server for more detailed information.

Documentation
There are two types of Maestro documentation:
 * Maestro documents
 * documentation relating to the principles of Maestro identified with the Maestro logo. This type of documentation can also be considered marketing documentation.
 * Swift Construction Company documents
 * documents relating to the principles, operations and practices of the fictional Swift Construction Company (the SCC), forming the Maestro Reference Design. SCC documents are usually identified with the SCC name, and may also be identified with the SCC logo.

License Statement

 * Maestro documents
 * (C) 2010 by Dale Scott. This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License. http://creativecommons.org/licenses/by-sa/3.0/
 * Swift Construction Company documents
 * (C) 2010 by Dale Scott. This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/

Attribution
References shall be cited using the Chicago Author-date style (The Chicago Manual of Style Online. Chicago-Style Citation Quick Guide. http://www.chicagomanualofstyle.org/tools_citationguide.html (accessed 2010-02-01)).


 * Examples (Reference List Entry, but also used here in-line when a seperate reference list is not provided)
 * Book, One Author: Doniger, Wendy. 1999. Splitting the Difference. Chicago: University of Chicago Press.
 * Book, Published Electronically: Kurland, Philip B., and Ralph Lerner, eds. 1987. The Founders’ Constitution. Chicago: University of Chicago Press. http://press-pubs.uchicago.edu/founders/ (accessed 2010-02-01).
 * Website: Evanston Public Library Board of Trustees. Evanston Public Library strategic plan, 2000–2010: A decade of outreach. Evanston Public Library. http://www.epl.org/library/strategic-plan-00.html (accessed 2010-02-01).

File Naming
Maestro files are informally named by purpose and include a 2-digit revision level. Spaces are not permitted within file names to simplify moving between file systems and management by web applications. When an export is made from a document, the export filename should be the same as the originating document with an explanatory suffix added.

Maestro Document Filename Syntax:

Maestro-[Purpose]-[RevisionLevel].ext Maestro-[Purpose]-[RevisionLevel]-[ExportDescription].ext

Maestro Document Examples:

Document Templates

 * Maestro presentations - use the Maestro presentation template (based on the OpenOffice.org "Blue Fluid" presentation template)

Fonts

 * Body font is preferably Arial for Maestro and Swift Construction Company documents
 * Title font is preferably Arial for Maestro documents
 * Title font is preferably Times New Roman for Swift Construction documents
 * Computer input and output font is preferably Courier

Artwork (Icons, Glyphs, Logos...)

 * Icons shall be used from the GPL-licensed GNU Desktop Icon set when available. http://commons.wikimedia.org/wiki/GNOME_Desktop_icons

Abbreviations and Acronyms
Abbreviations and acronyms are a form of shorthand a community uses. The first time an acronym appears in a general document (whether on a web or wiki page, in an OpenOffice.org Writer or Microsoft Word file, etc.) a definition shall immediately follow in brackets.

When brevity is extremely important, the abbreviation or acronym need not be defined (e.g., in an OpenOffice.org Impress or Microsoft PowerPoint presentation).

Page Sizes

 * Maestro and Swift Construction Company documents should use ANSI-A, ANSI-B or ANSI-C (in order of preference, for ease of hardcopy reproduction and standardization).

ISO paper sizes are shown below for comparison: