grunt-phantomas/CONTRIBUTING.md

Grunt plugin for phantomas

# grunt-phantomas

You decided to contribute to this project? Great, thanks a lot for pushing it.
I really care about the coding style in this project and can be really picky to keep the project pretty. ;)

Before you make a pull request please check these points:

## Editor settings
- please set up your editor to use two spaces
- remove spaces at line endings or empty lines
- make sure all files end with one empty line

## Coding style

#### I really like spaces, because I think they improve the readability a lot. Please try to keep that in mind.

Not desired:

```
if(a===b) {console.log('foo');}
```

Desired:

```
if ( a === b ) {
  console.log( 'foo' );
}
```

Not desired:

```
function(a,b,c){
  console.log('foo');
}
```

Desired:

```
function( a, b, c ) {
  console.log( 'foo' );
}
```

#### Please keep everything aligned.

Not desired:

```
a = {
  fooooooo: 'foo',
  bar: 'bar
}
```

Desired:

```
a = {
  foooooo : 'foo',
  bar     : 'bar
}
```

#### Please try to stick to line max character number of 80.

I know that it is sometimes unavoidable to go over it. But function arguments and long if-conditions can inlcude line breaks. ;)

#### Functions are sorted alphabetically.

I know, that a lot of people do not agree with that. Never the less, I really like it and it helps me a lot. Please try to stick to it.


#### Please don't forget to add JSDoc to every new implemented function.

#### Please don't forget to check existing unit tests and/or implement new unit tests for new functionality.

Tested functions should include `@tested` param in particular JSDoc block.

#### Make sure your contribution is passing at travis. You can check that also locally buy running 'grunt test'.

`grunt test` will run unit test suite, JSHint and JavaScript Code Style checker. Make sure all of them pass.

## Workflow

To make changes to the styles, scripts or templates there is a particular workflow needed, because the result page is rendered by the task itself.

First step is to clone the repository and run a `npm install` to get it up and running.
After that the project is able to run `phantomas` itself by executing `grunt phantomas`. You will find the depending settings inside of the `Gruntfile.js`.

### Changing generated markup

To change the generated markup you have to run the task after each change you made by running `grunt phantomas`. This is a bit unconvenient, but there is unfortunately no other way to work on it, because the HTML is generated by running the task.

You will find the base for the generated UI at `tasks/tpl`.

To check made changes I usually navigate into the `phantomas` folder that includes the generated result and execute a `server` command.

```
stefan @ stefan-mac: ~/Sites/grunt-phantomas master (╯°□°)╯
> cd phantomas

stefan @ stefan-mac: ~/Sites/grunt-phantomas/phantomas master (╯°□°)╯
> which server
server: aliased to open http://localhost:8000 && python -m SimpleHTTPServer

stefan @ stefan-mac: ~/Sites/grunt-phantomas/phantomas master (╯°□°)╯
> server
```

### Changing scripts and styles

To change JavaScript and CSS and you have to run the task at least once. Then navigate into the generated `phantomas` directory and start a preview server (check 'Changing generated markup' to see how).

When you see the generated UI, you can kick off a file watcher by executing `grunt watch` which will automatically update the loaded asset files in the generated UI.

Final JS and CSS files are generated and you will find the base files inside of the `tasks/assets` folder.

```
stefan @ stefan-mac: ~/Sites/grunt-phantomas master ヾ(⌐■_■)ノ
> cd tasks/assets

stefan @ stefan-mac: ~/Sites/grunt-phantomas/tasks/assets master (╯°□°)╯
> ll

drwxr-xr-x  6 stefan  staff   204B  5 Sep 13:04 sass/
drwxr-xr-x  4 stefan  staff   136B 28 Sep 01:59 scripts/
```