Add some documentation collected from GitHub comments

elkuku · elkuku · commit 0bb506411ee7 · 2013-05-24T15:44:20.000-05:00
diff --git a/Documentation/CLI-skript.md b/Documentation/CLI-skript.md
@@ -0,0 +1,65 @@
+# tracker.php
+
+This script will do:
+
+* Setup the required database for the application.
+* Initial import and further update of issues and issue comments from GitHub.
+
+It is meant to be used during the development process and must be run from the PHP command line interface.
+
+Usage:
+
+`tracker.php <command> [action]`
+
+Available commands:
+
+* `install` Install the application.
+* `retrieve` Retrieve new issues and comments
+* `help` Display some helpful text.
+
+For more information use `tracker.php help <command>`.
+
+## Install the application
+
+Copy `/etc/config.example.json` to `/etc/config.json` and fill in your database details.
+
+Then run:
+`tracker.php install`
+
+## Retrieve new Issues and Comments
+
+`tracker.php retrieve issues`
+
+`tracker.php retrieve comments`
+
+## Colors
+Recently a new feature has been added to the framework that allows CLI applications to display colorful output on ANSI enabled terminals. So I thought we might see how it looks and feels ;)
+
+ANSI color codes are supported in most (if not all) *nix style terminals.
+To test this feature I grabbed a VM with Windows XP, installed git for Windows and GitHub (both include terminals) but neither them nor the standard Windows thingy supported ANSI colors.
+Then I installed [Cygwin](http://www.cygwin.com/) (which is a good choice anyway), and got the following output:
+![win-colors1](https://f.cloud.github.com/assets/33978/491726/2c5ff9b4-ba54-11e2-80eb-76a29914d58a.png)
+
+## Progress Bar
+Since we have some long runng operations (currently ~10 min pulling the CMS issues on my slow i-net), I thought we might use some "high class" progress bar.
+
+The progress bar is not part of the repo and has to be installed using composer from [elkuku/console-progressbar](https://packagist.org/packages/elkuku/console-progressbar) (which is a fork of [PEAR/Console_ProgressBar](http://pear.php.net/package/Console_ProgressBar) with a facelifting ;)
+I haven't tried that on windows, but it might work on cygwin...
+![progressbar3](https://f.cloud.github.com/assets/33978/491733/a36ce152-ba54-11e2-8c06-179b6a379876.png)
+
+## Unsupported...
+If your terminal does not support ANSI control codes you may see something like this:
+![win-colors-fail](https://f.cloud.github.com/assets/33978/491728/57cc233e-ba54-11e2-9c6b-154ad99488fd.png)
+
+## Turn it off !
+To suppress color ouput for a single command use the `--nocolors` switch.
+To suppress the progress bar for a single command use the `--noprogress` switch.
+Example:
+`tracker.php retrieve issues --nocolors --noprogress`
+
+To turn the feature(s) off permanently edit `etc/config.json` and set the values for the undesired features from `1` to `0`.
+
+----
+Since most of the code in this PR has been used to actually test this feature before submitting it to the framework, I thought I could give this here back too.
+
+If you have any strong feelings against this, please raise your voice here and now or I am going to merge it ;)
diff --git a/Documentation/access-control.md b/Documentation/access-control.md
@@ -0,0 +1,14 @@
+## Access control
+Acces control is limited and very specific:
+
+* Only **Projects** are tracked.
+* There are only 4 "hard wired" **Actions**:<br />`view`, `create`, `edit` and `manage`.
+* It is based on **groups** a user automatically belongs to or can be assigned to.<br />
+For every project two **system groups** are created by default:<br />`Public` and `User`.
+
+The special **admin user** role that is assigned using the `config.json` file is granted global access.
+
+Following is an example setup for a security tracker with non public access and two additionally created custom groups:
+![Access groups](https://f.cloud.github.com/assets/33978/550822/fc7c42a0-c31a-11e2-82c8-85f4ea05b92e.png)
+
+However, this is a very first step... lots of optimization and testing required here.
diff --git a/Documentation/avatars.md b/Documentation/avatars.md
@@ -0,0 +1,7 @@
+## Avatar support
+
+On the first log in, the application tries to fetch the users avatar and store it locally.
+
+The command `cli/tracker.php retrieve avatars` will fetch the avatars for the users that appear in the `#__activities` table.
+
+**This requires cURL.** - since a redirect is made which J\Http (or me) is unable to handle properly.
diff --git a/Documentation/config-editor.md b/Documentation/config-editor.md
@@ -0,0 +1,5 @@
+## Config editor
+There is a "system component" that currently displays a config editor using simple text fields where you can fill in the values.
+Saving is not provided yet. When hitting the save button the config is written to the screen where you might copy&paste it ;)
+If you are on PHP < 5.4 there will be only a "compressed" version of the JSON string (a "pretty print" function could be written).
+TBH - I only wrote this because it requires very little code and at some point we (or whoever uses a JSON based config file) might think about an UI for editing it.
diff --git a/Documentation/database.md b/Documentation/database.md
@@ -0,0 +1,4 @@
+## Database updates
+Obsolete tables and table fields have been removed while others have been added ;)
+
+**Full reinstall required !**
diff --git a/Documentation/debugging.md b/Documentation/debugging.md
@@ -0,0 +1,17 @@
+## Debugging and Logging
+
+Added a TrackerDebugger class that... handles debugging :P
+Added a CallbackLogger class to provide database query logging.
+A log file can be written to log queries even during redirects ;)
+Exception rendering has been improved to include clickable file links using the xdebug protocol.
+
+### Log files
+To activate or deactivate logging use the `debug.logging` option in `etc/config.json`.
+
+Supported log events:
+* 403
+* 404
+* 500
+* database queries
+
+The supported "events" will be written to their proper log file. Unsupported events go to the `500.log`.
diff --git a/Documentation/github-authentication.md b/Documentation/github-authentication.md
@@ -0,0 +1,22 @@
+## GitHub Authentication
+
+GitHub limits requests to its API to 60 per hour for unauthenticated requests, and to 5000 per hour for requests using either basic authentication or oAuth.
+
+For the initial import of issues and issue comments to the database we need to authenticate with GitHub to avoid to exceed the rate limit.
+
+To use your GitHub credentials from the CLI script, edit the `config.json` file and fill in your GitHub username and password, answer "yes" to the question if you whish to authenticate, or pass the `--auth` option.
+
+This will add the possibility to authenticate a user with his/her GitHub account using oAuth authentication.
+
+#### oAuth login
+In order to test the login feature in your local environment you will need to create an application `key` and `secret` for your (local) JTrackerApplication instance:
+
+* Sail to your account on GitHub &rArr; "Edit your Profile".
+* Go to "Applications" - "Developer applications" and "Register new application"
+* Fill in some name and some main url. Those will be presented to the user when authorizing the application.
+* Fill in a domain for callback URL. This **must match** the domain the application is running. This may be `http://localhost` or a virtual host.
+* Hit "Save" and copy the client_id and client_secret.
+* Edit `config.json` and fill in the `client_id` and `client_secret`.
+* Install as usual.
+* Sail to your localhosts JTracker installation and click on "Login with GitHub"
+* On the first attempt you will be redirected to GitHub where you have to confirm the access by your application.
diff --git a/Documentation/pagination.md b/Documentation/pagination.md
@@ -0,0 +1,15 @@
+## Pagination
+
+I searched the web for "PHP pagination MySQL" or similar, and this came up on the first page:
+http://www.awcore.com/dev/1/3/Create-Awesome-PHPMYSQL-Pagination_en
+
+I liked the way the author solved "the problem", the code looked acceptable,... so I "forked" and Joomla!"d it :)
+The CSS was somewhat conflicting (for me), so I took one of the beautiful styles from the author, and now it looks like this:
+
+![Pagination](https://f.cloud.github.com/assets/33978/550842/960024f0-c31b-11e2-971c-c7d870320600.png)
+
+For now it only generates "plain links" adding a `&page=n` parameter to the current URL.
+When we implement the search functionality, this must be revised.
+I can also imagine a JavaScript (AJAX) based solution using this.
+
+**Note**: The license on this is very unclear. Seems that is provided as a "snippet". Maybe our legal department should have a look at this ;)
diff --git a/Documentation/session.md b/Documentation/session.md
@@ -0,0 +1,4 @@
+## Session management
+Is provided by the [session subsystem from the Symfony2 HttpFoundation Component](http://symfony.com/doc/master/components/http_foundation/sessions.html)
+
+The new possibilities are still to explore....
