# Contributing to bluebird

1. [Directory structure](#directory-structure)
2. [Style guide](#style-guide)
3. [Scripts and macros](#scripts-and-macros)
4. [JSHint](#jshint)
5. [Testing](#testing)

## Directory structure

- `/benchmark` contains benchmark scripts and stats of benchmarks

- `/browser` contains scripts and output for browser testing environment

- `/js` contains automatically generated build output. **NOTE** never commit any changes to these files to git.

    - `/js/browser` contains a file suitable for use in browsers
    - `/js/main` contains the main build to be used with node. The npm package points to /js/main/bluebird.js
    - `/js/debug` contains the debug build to be used with node. Used when running tests
    - `/js/zalgo` contains the zalgo build not to be used by any mortals.

- `/node_modules` contains development dependencies such as grunt

- `/src` contains the source code

- `/test/mocha` contains tests using the mocha testing framework

## Scripts and macros

Scripts and macros are necessary for the code the code to remain readable and performant. For example, there is no way to turn the `arguments` object into an array without using a build step macro unless you want to compromise readability or performance.

`/ast_passes.js` contains functions called ast passes that will parse input source code into an AST, modify it in some way and spit out new source code with the changes reflected.

`/src/constants.js` contains declarations for constants that will be inlined in the resulting code during in the build step. JavaScript lacks a way to express constants, particularly if you are expecting the performance implications.

`/Gruntfile.js` contains task definitions to be used with the Grunt build framework. It for example sets up source code transformations.

`/bench` a bash script to run benchmarks.

`/mocharun.js` a hack script to make mocha work when running multiple tests in parallel processes

## JSHint

Due to JSHint globals being dynamic, the JSHint rules are declared in `/Gruntfile.js`.

## Style guide

Use the same style as is used in the surrounding code.

###Whitespace

- No more than 80 columns per line
- 4 space indentation
- No trailing whitespace
- LF at end of files
- Curly braces can be left out of single statement `if/else/else if`s when it is obvious there will never be multiple statements such as null check at the top of a function for an early return.
- Add an additional new line between logical sections of code.

###Variables

- Use multiple `var` statements instead of a single one with comma separator. Do not declare variables until you need them.

###Equality and type checks

- Always use `===` except when checking for null or undefined. To check for null or undefined, use `x == null`.
- For checks that can be done with `typeof`: do not make helper functions, save results of `typeof` to a variable or make the type string a non-constant. Always write the check in the form `typeof expression === "constant string"` even if it feels like repeating yourself.

## Testing