PiAnoS 4 / tools / README.txt
=============================

This directory, only available in the Subversion repo (not in the release tarballs),
contains various tools to:
- generate release/SDK tarballs
- build the documentation
- test/fix/automate various things

Only the first 2 points are actually supported - the rest is left so it can
be reused if needed, but is not part of the official tools suite.

DEVELOPMENT VERSION VS. RELEASE VERSION VS. SDK
===============================================

The SVN tree is a bit complex and contains too many files for simple release
distributions (i.e. releases that administrators will install and run on their
server). Further, the file layout is optimized for development in an 
environment where e.g. a CDN is available for dependencies, where the various
PHP libraries are available, etc. Finally, it includes unpublished features
that we use internally for research.

So, if you are a developer, you need the SDK (for all users) or an SVN 
snapshot (if you work here at ESC).

If you are an administrator and are looking to install PiAnoS on your server,
you need the release tarball. Note that it is perfectly possible to install
a development version, but this requires many manual steps and is a tedious
and error-prone process. Better use the release tarballs (unpack, run).

Starting with version 4.2, an SDK is also available. It allows developers that
do not have access to the full SVN version to modify PiAnoS in its "source"
form (e.g. non minified Javascript files). This SDK is different from the SVN
version, and is produced by the build.py script (using different options).



CURRENT STATUS OF THE LICENSE W.R.T. VERSIONS
=============================================

Currently, only the release/SDK tarballs are meant to be distributed. The 
complete source version is NOT licensed in any way, and MUST NOT be 
distributed as is, whatever the reason.
If it needs to be distributed, a license has to be defined for these files and
everything must be validated (i.e. by someone competent in license issues) 
before any form of distribution can take place.

The tarballs are licensed under the AGPL, and can be freely distributed.

The deep reason why the SVN is not licensed is to allow the dissemination of
PiAnoS while still keeping "private" the parts (e.g. SQL schema generation)
that are not part of this project and that should stay out of sight of users.
However, the UNIL-PHP library has been fully integrated into PiAnoS. This is
not a problem since it has been designed for it - and other applications that
rely on it are not distributed for the moment.

But there are lots of issues that prevent a licensed full source distribution
for the moment. Again these have to be solved properly before anything is
decided.


GENERATING A TARBALL RELEASE
============================

[NOTE: 'build.py' requires the Google closure compiler. Please download it from 
http://dl.google.com/closure-compiler/compiler-latest.zip, and save 
'compiler.jar' in the tools/ directory, just next to 'build.py']

To generate the said release tarballs, a build script is available: build.py.
You can get quite some help using '--help' (wow!).

A shorthand is available on Windows: 'make.bat'. This will:
- run build.py with local (my development system's) options set
- create 'pianos-latest.tar.gz' (to be uploaded to the website)

Since using 'build.py' script is not simple, you may want to refer to 
'make.bat' to see how options are meant to be used.

SDK tarballs are generated using the same script, with different options,
namely '--inc-doc-src --inc-src --inc-demo --output pianos-sdk'.


THE DOCUMENTATION
=================

The source tree contains the source to the documentation, in the form of a
Sphinx project. Sphinx 1.1.3 is used, but other versions should work as well.

The 'build.py' takes care of calling the documentation build script if needed,
but if you wish to edit the documentation, you can go to the doc/ directory
where there is this 'make.bat' file that does everything for you. (The doc/
directory is a standard Sphinx-generated directory).


NOTES SPECIFIC TO ips-labs.unil.ch
==================================

ips-labs.unil.ch is the application server where PiAnoS is deployed for our
internal use. It contains several instances of PiAnoS, each at a different
version (I don't force upgrades, except for the 'students' version), and
each connected to a different database.

Facts (current as of 08.02.2013):
- PiAnoS, as deployed on ips-labs.unil.ch, is built using 'make.bat --inc-shib'
- Current release tarballs, as downloadable from our server, are built using 'make.bat --inc-doc'
- SDK tarballs are built using 'make.bat --inc-doc-src --inc-src --inc-demo --output pianos-sdk'

ips-labs.unil.ch also hosts the public documentation (the same that is 
included in the tarball), so this must be kept up to date with the latest
PiAnoS version - manually, sorry.

To perform an update on a production instance:
- ideally, shutdown the web server (so that nobody is connected)
- backup the database
- unpack the release in a new directory under /var/www/apps-available
- edit the 'settings-local.php' configuration file (most probably by copying
  the previous version's and making required changes)
- change the symlink in /var/www/apps-enabled to point to the newly created
  directory
- test
- re-enable access for everyone



To perform a documentation update:
- copy the doc/build/html/ directory to somewhere
- make sure the symlink /var/www/pianos-www points to this directory
  (currently it points to /home/tibo/pianos-docs)
- create a downloads/ folder
- put all downloadable releases here

The process for the doc is a bit weird, but this is because I use the same
website for both the documentation (which could have been a PDF, a word
doc, etc.) AND the application (which has to be a website, where you can
download the program, submit bugs, etc.). Obviously, the standard 
documentation is not 100% the same as the website, hence the need to create
the downloads directory.




OTHER TOOLS IN THIS DIRECTORY
=============================

Most Python scripts here will have a name that tries to indicate what they do,
and should also respond to --help with interesting information.

These have been created to cope with very specific problems (e.g. schema 
migrations during early development, creation of batches of users, ...) and
are not guaranteed to do anything useful as of now.

WARNING: Use them with care as you are on your own !
