<!-- 
/*
Copyright 2017 apHarmony

This file is part of jsHarmony.

jsHarmony is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

jsHarmony 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this package.  If not, see <http://www.gnu.org/licenses/>.
*/
-->
<script type="text/x-tutorial-info">
{
  "Title": "Contributing",
  "Menu": ["Getting Started"]
}
</script>
<h3>Introduction</h3>
The jsHarmony projects are open source and available on GitHub.  We would love to include your contributions - whether bug fixes, documentation, or new features.<br/>
<br/>
The following are the key projects in the jsHarmony system:
<ul>
  <li><b>jsharmony</b> The core jsHarmony application</li>
  <li><b>jsharmony-factory</b> Template database tables and user interface for enterprise applications (users, menu, list of values tables, audit trail, documents, notes, etc)</li>
  <li><b>jsharmony-db</b> Database driver core</li>
  <li><b>jsharmony-db-pgsql</b> PostgreSQL database driver</li>
  <li><b>jsharmony-db-mssql</b> SQL Server database driver</li>
  <li><b>jsharmony-db-sqlite</b> SQLite database driver</li>
  <li><b>jsharmony-validate</b> Validators (shared between client and server code)</li>
  <li><b>jsharmony-cli</b> Command line interface</li>
  <li><b>jsharmony-tutorials</b> Tutorials and reference documents</li>
</ul>

<h3>jsHarmony</h3>
The jsHarmony application consists of client-side and server-side components.<br/>
<br/>
The server started using "nstart.cmd" (Windows) or "nstart.sh" (Linux).  The "supervisor" command in that batch file automatically restarts if any files have been changed.<br/>
<br/>
When updating the jsHarmony Core, it is recommended to add the relevant to modules to the auto-restart process, ex:
<pre>
supervisor -i clientjs,test,public,data,./models/sql,./node_modules/jsharmony-db-mssql/node_modules,./node_modules/jsharmony-db-sqlite/node_modules,./node_modules/jsharmony-db/node_modules,./node_modules/jsharmony-cms/node_modules,./node_modules/jsharmony-factory/node_modules,./node_modules/jsharmony/node_modules -w "./node_modules/jsharmony,./models,./views,./node_modules/jsharmony-factory,./node_modules/jsharmony-db,./node_modules/jsharmony-db-mssql,./node_modules/jsharmony-db-sqlite,./app.config.js,./app.config.local.js" -e "node,js,json,css,ejs,sql" node "./app.js"
</pre>

<h3>Linking jsHarmony Modules</h3>
In order to link the modules, it's recommended to download the source and then use the "npm link" command to link the module to a jsHarmony Application, ex:
<pre>
c:\wk\jsharmony (jsHarmony Core)
c:\wk\testapp (jsHarmony Application)

cd c:\wk\jsharmony
npm link
cd c:\wk\testapp
npm link jsharmony
</pre>
NPM currently has a bug, where any linked modules are unlinked during an "npm install" or "npm update".  If performing development on multiple modules, avoid using "npm install" and "npm update", and instead inter-link the modules and use Git to pull the latest versions.<br/>
<br/>
Alternatively, "yarn" can be used as a replacement for NPM.

<h3>clientcompiler.cmd</h3>
The client-side JS is compiled using clientcompiler.cmd.  This takes the files from the "jsharmony\clientjs" folder and compiles them into "public\js\jsHarmony*.js".<br/>
<br/>
Since the compilation process will generate different files based on the Node.js version, developers should use the following workflow for local development:
<ol>
  <li>
    In app.config.[localmachine].js, set config.debug_params.dev_client_js = true<br/>
    <i>This will cause jsHarmony to load "public/js/jsHarmony.dev.js" instead of "public/js/jsHarmony.js" client-side</i>
  </li>
  <li>
    Run "clientcompiler.cmd"<br/>
    <i>This will compile clientjs/jsHarmony.js into public/js/jsHarmony.dev.js.  The generated jsHarmony.dev.js file is .gitignore(d) in the repo</i>
  </li>
</ol>
Then, once the updates are ready to be merged into the master branch, the repo maintainer or automated build process will run the final production compilation / minification to generate "public/js/jsHarmony.js"  This is done by executing "clientcompiler.cmd /prod" from a dedicated deployment machine<br/>
<br/>
clientcompiler.cmd has the following requirements:
<ul>
  <li>npm install -g browserify</li>
  <li>npm install -g supervisor</li>
  <li>npm install -g uglifyjs</li>
</ul>
The batch file uses supervisor to watch for changes and automatically recompile when a dependent file is changed.
