CONTRIBUTING.md

How to contribute to Bookshelf.js

• Before sending a pull request for a feature or bug fix, be sure to have tests.

• Use the same coding style as the rest of the codebase.

• Make changes in the /src directory, running "npm run dev" which will kick off transpilation from ES6 in the background.

• All pull requests should be made to the master branch.

Development Environment Setup

You'll need to have git installed obviously. Begin by forking the main repository and then getting the code from your forked copy:

$ git clone git@github.com:yourusername/bookshelf.git

Afterwards go to the bookshelf directory that was just created and install the dependencies:

$ npm install

At this point the only thing missing are the databases that will be used for running some of the tests of the automated test suite.

There are two options for setting up this part. The first one is to change some configuration options of the database servers and the other is to use a config file in case you already have your servers configured and don't want to change any of their config files. The first two sections below deal with the first option and then there are instructions on how to use the other option.

MySQL

You can install MySQL easily on most linux distros by using their package manager. With Ubuntu this should do it:

$ sudo apt-get install mysql-server mysql-client

On OSX you can download a disk image directly from the MySQL Downloads page, or use one of the popular package managers like homebrew or MacPorts.

To run the test suite you will need to make sure it is possible to connect as the user root without the need for a password.

It is strongly recommended that you use the command line mysql client to access your MySQL instance since there can be problems connecting as the root user with some graphical clients like phpMyAdmin. To check if you can connect as root without needing a password use the following command:

$ mysql -u root

If you see an error like:

ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)

that means you can't login as root without a password. If you do know the root user's password just login with the known password like this:

$ mysql -u root -p

and enter the password when asked. Then just set an empty password for root like so:

USE mysql;
UPDATE user SET password = "" WHERE User = "root";
FLUSH PRIVILEGES;
QUIT;

Note that you'll probably need to set the password to NULL instead of an empty string in MySQL versions 5.5 and older. The above example should work with versions 5.6 and newer.

If you have forgotten the root password you'll need to take some extra steps to reset it. Take a look at this Stack Overflow answer for further details.

PostgreSQL

You can install PostgreSQL easily on most linux distros by using their package manager. With Ubuntu this should do it:

$ sudo apt-get install postgresql postgresql-client

On OSX the easiest way is probably by using PosgresApp. It should also be available to install via homebrew or MacPorts if you prefer.

In the case of PostgreSQL the requirement is to be able to connect as the postgres user on localhost also without the need for a password. This can be achieved by editing or adding the following line in the pg_hba.conf file:

host    all             all             127.0.0.1/32            trust

This file can be found in /etc/postgresql/9.4/main/ on most linux systems. The 9.4 part could be different depending on the version that is available in your distro. On OSX the location of this file will depend on the installation method chosen, but for the recommended PostgresApp install it will be in /Users/[yourusername]/Library/Application Support/Postgres/var-9.3/. Again, the var-9.3 part may be different depending on the version you installed.

The trust in the example above tells the locally running PostgreSQL server to ignore user passwords and always grant access on clients connecting locally. Do not use this setting in a production environment.

After editing the pg_hba.conf file you'll need to restart the PostgreSQL server for the changes to take effect.

Using a config file

If you don't want to go to the trouble of performing the changes explained in the previous two sections you can instead use a config file that tells the test suite about your database setup.

The tests will look for a BOOKSHELF_TEST environment variable that points to a config.js file with the connection details for each database server. This file must not be the same database config file you use for any other application, otherwise you risk data loss in that application.

Example config file:

module.exports = {
  mysql: {
    database: 'bookshelf_test',
    user: 'root',
    encoding: 'utf8'
  },

  postgres: {
    user: 'myusername',
    database: 'bookshelf_test',
    password: 'secretpassword',
    host: 'localhost',
    port: 5432,
    charset: 'utf8',
    ssl: false
  },

  sqlite3: {
    filename: ':memory:'
  }
};

This file can be placed anywhere on your system and can have any name that you like, as long as the environment variable is pointing correctly to it. For convenience you can put it in your home directory and add the following line to your .bashrc or .zshrc:

export BOOKSHELF_TEST='/home/myusername/.bookshelf_config.js'

Database creation

After having ensured the test suite can access both database servers just create a new database on each that will be used exclusively by Bookshelf.js:

CREATE DATABASE bookshelf_test;

Running the Tests

The test suite requires that both MySQL and PostgreSQL servers have a database named bookshelf_test. See the sections above for further instructions.

Once you have done that, you can run the tests:

$ npm test

Always make sure all the tests are passing before sending a pull request.