search

opinsys / puavo-ticket

https://huboard.com/opinsys/puavo-ticket
GNU General Public License v2.0
3 stars 0 forks source link

readme

puavo-ticket

Cool new ticketing system with deep puavo integration.

Table of Contents generated with DocToc

Roles

The system has currently only to types of users. Managers (Opinsys staff in our case) and clients.

There are currently only two differences:

  1. Clients can only see the tickets they have visibility to - managers can see all the tickets
  2. Managers can add handlers to tickets

Ticket handler

When client has only a visibility to a ticket he/she do following:

but when user is a handler for a ticket he/she can also:

Ticket creator is automatically a handler.

Visibilities

Users and tickets have visibility properties. Users see the tickets where the visibility properties match.

A client has following visibility properties by default:

When ticket is created it will get only the visibility of the user who created it. Ticket will get additional visibilities when:

Development Documentation

Project structure

Installation for development

Apply Ansible rules from puavo-standalone.

Clone this repository and install build dependencies

sudo make install-build-dep

Install node.js modules and build Javascript assets

make

Run database migrations for testing database

NODE_ENV=test make migrate

Stop the puavo-standalone installed puavo-ticket server and start a development server

sudo stop puavo-ticket
make server

Development tools

First install the local git pre-commit hooks

make install-git-hooks

This will prevent you from committing broken or trivially bad Javascript. It uses JSHint to automatically validate the staged Javascript files when you try to commit them.

and start puavo-web and puavo-rest

make puavo-start

Editors

Better yet you should integrate real time JSHint validation to your editor.

You will also want a JSX support if you edit anything under components/. When editing them jsxhint wrapper for JSHint must be used. It's installed in node_modules/.bin/. jsxhint can be used for the plain js files too.

See http://facebook.github.io/react/docs/tooling-integration.html#syntax-highlighting-amp-linting

Setup PATH

You might want to put locally installed node.js tools to your path

export PATH="$(pwd)/node_modules/.bin:$PATH"

or use the shortcut

. .bash_node_modules

This will give you direct access and tab completion to mocha, jsxhint and other tools.

Database REPLs

Start node.js/Bookshelf repl with make repl. All models should be in scope. The repl is based on repl-promised.

Start PostgreSQL psql repl use make psql.

Both of these respect the the NODE_ENV=test environment variable.

Tests

Basics

Acceptance tests

The test are written using the wd module and Selenium WebDriver. The Ansible rules will configure upstart scripts for Selenium and Xvbf X server for you.

To run the tests type

make test-acceptance

If you want to debug the tests in a local browser you must run the Selenium server on your local machine and forward it to the puavo-ticket development machine.

First stop the Selenium service on the puavo-ticket machine

sudo stop selenium

Then on the local machine fetch the Selenium server

wget http://selenium-release.storage.googleapis.com/2.43/selenium-server-standalone-2.43.1.jar

Start it

java -jar selenium-server-standalone-*.jar

And forward it to the puavo-ticket machine

ssh <puavo-ticket machine host> -R 4444:localhost:4444 -o "ExitOnForwardFailure yes" read

Debug browser Javascript

For any browser code you can just add a debugger; statement and the browser break on it when devtools are open.

Debug server Javascript

For server code to break on debugger statements you must start the server with the debug command:

node debug server.js

This will break on the first line. Use enter c to continue. See node.js debbugger documentation for more information.

Debug server tests

Server-side tests can be debugged similarly using the mocha command:

mocha debug test/api/tickets_test.js

If you like GUIs the server can be debugged with node-inspector too.

Debug SQL

Set SQL environment variable to 1 or true

Example: SQL=1 make test-server or SQL=1 node server.js

Debug logging

We are using the debug module. For each .js file create own debug instance with a name puavo-ticket:<path> where the <path> is the path for the .js file. For more specific loggers a symbolic name can be used.

Example:

var debug = require("debug")("app:resources/tickets");
var debugMail = require("debug")("app:mail");

Using the app: prefix we can enable debug logging for puavo-ticket server with a DEBUG environment variable:

DEBUG=app:* node server.js

or for the browser using a Javascript console:

debug.enable("app:*");

Coding conventions

ECMAScript 6

We use babel (node) and react-tools es6 option (browser) for ECMAScript 6 support. Please use the features conservatively.

Only

Mainly fat arrows and classes for now.

Styles

We are using Bootstrap, Bourbon and React Bootstrap. See documentation in:

Every component should have a className prop containing the component name and a corresponding stylesheet next to it using the component name as a prefix for the component specific styles.

Example:

FooComponent.js

var FooComponent = React.createClass({
    render: function() {
        return <div className="FooComponent"><a href="https://github.com/opinsys/puavo-ticket/blob/master/">foo</a></div>;
    }
});

FooComponent.scss

.FooComponent {
    a {
        color: hotpink;
    }
}

puavo-ticket API documentation

The Javascript API documentation is generated with YUIDoc and is available in

http://opinsys.github.io/puavo-ticket/

React components

Document all the props. Example:

/**
 * YUIDoc documentation
 *
 * @namespace components
 * @class FooComponent
 * @constructor
 * @param {Object} props
 * @param {String} props.url Url for the link
 **/
var FooComponent = React.createClass({

    propTypes: {
        url: React.PropTypes.string.isRequired
    },

    render: function() {
        return <div className="FooComponent"><a href={this.props.url}>foo</a></div>;
    }

});

REST API documentation is generated using apiDoc from resources/ and is available in

http://opinsys.github.io/puavo-ticket/rest/

Documentation can be build with make doc and published with make doc-publish. During development the documentation is also available in /doc from the puavo-ticket server.

External documentation

For testing