Contributing

Contributing to Jamstash

Here are the commands needed to work on Jamstash. Please take a moment to read them and thank you for contributing to Jamstash !

Installing npm, bower and grunt

In order to work on Jamstash, you'll need severals tools commonly found on Javascript front-end projects: npm, bower and grunt.

npm is a package manager for javascript. Its purpose is to make it easier for you to download and install javascript programs. We'll use it to install the other tools.

First, download and install Node.js, which installs npm with it (as npm, bower and grunt all need Node.js to run).

Install npm

Then, open a shell and run npm --version. It should display a version number which means it is correctly installed.

To install bower and grunt, run the following command:

npm install -g bower grunt

The -g flag is for "global" which means it will install them on the system and not locally in the current directory. We'll be able to use them on the command line just like npm.

You can also check that the commands work using grunt --version or bower --version.

Here are links to bower's website and grunt's website if you need more information on them.

Working on Jamstash: first run

Assuming you have forked and cloned Jamstash using Github, you'll need to run a couple of commands to get it to work.

As is the custom with projects using npm or bower, we don't include a project's dependencies in Git because these represent thousands of files that can change dependending on your OS. We only include a description of the version we depend on in a json file: package.json for npm and bower.json for bower. That means you'll need to download those dependencies yourself using the tools.

Here's how it's done. Assuming you have a shell open and the current directory is Jamstash, run the following command to install all npm-managed dependencies (it may take a few minutes):

npm install

Next, run the following command to install all bower-managed dependencies:

bower install

You'll end up with the node_modules and bower_components directories. Those contain the dependencies we need to run Jamstash in dev and are purposefully excluded from Git.

Sometimes, we might add or change Jamstash's dependencies, or authors might push bugxfixes of those dependencies. In those cases please run the following commands in Jamstash's directory to update them.

npm update
bower update

To remove dependencies which are no longer needed, use:

npm prune
bower prune

Working on Jamstash

Using grunt, we have defined a number of useful grunt build commands to ease development.

Assuming you have a shell open and the current directory is Jamstash, run the following command to spin up a webserver with live-reload capabilities and run karma, which opens up a Chrome browser to run unit-tests in. The great thing about this command is that anytime you'll save a html, css or js file, it will reload the page automatically and run the unit-tests so you can get the fastest feedback. The test results will be displayed with Growl or Windows 8 notifications and also in the shell.

grunt serve

The command runs indefinitly, to stop it simply kill it with CTRL+C.

Another useful command to run all the unit tests using Karma, analyze their line coverage and open up the report in a web browser. It tells you what lines of the code are covered by unit tests, so you can know where tests need to be added or if some edge-case is not tested. It'll spin a webserver to present the html results produced in the coverage directory.

grunt coverage

The command runs indefinitly, to stop it simply kill it with CTRL+C.

Bumping up Jamstash's version

Jamstash uses Semantic Versioning to manage its versions. Since there are 3 json files to maintain (package.json, bower.json, manifest.json), we've also added the grunt-bump plugin to make it easier. Whenever you submit a Pull Request and want to increase the version number, use one of the following commands where appropriate (use Semantic Versioning to guide your choice) :

# from 4.3.2 to 4.3.3
grunt bump:patch
# from 4.3.2 to 4.4.0
grunt bump:minor
# from 4.3.2 to 5.0.0
grunt bump:major

Minifying Jamstash for deployment

Grunt enables us to easily minify all the components of the website: html, css and js. This makes Jamstash much faster in production.

To run the build and minification process, use the following command:

grunt

The resulting files will all be in the dist/ folder.

Manually deploying Jamstash

Simply copy the dist/ folder to the configured folder of your webserver, e.g. /var/www/jamstash/, assuming you have already configured Apache or nginx or whatever.

Automatically deploying Jamstash on your test server

If you have a server accessible with ssh, you can use a single command to clear up everything and upload Jamstash on it using sftp.

First, create a .ssh/ folder in the Jamstash directory. Then, create a testServer.json file in it and fill the following information:

{
	"host": "my-test-server.example.org",
	"username": "my-username-on-the-server"
}

You have two choices to authenticate: either add a "password": "my-password-for-the-given-username" line on the above file, or use SSH public keys.

In order to use SSH keys, you'll need to first set them up on the server, which I'm not gonna explain here. After setting it up, copy the ssh private key used to gain access to the server with the given username into the .ssh/ folder and rename it into test-server-key.

The .ssh/ folder should thus contain one or two files, depending on your choice: testServer.json only if you choose to use a password, and both testServer.json and test-server-key if you use the keys.

Once the setup is done, you can simply run the following command to build Jamstash and upload the dist/ folder to your server in the /var/www/jamstash/ folder. CAUTION: the command will also remove everything (rm -rf) in the /var/www/jamstash/ folder, in order to effectively keep only the newest files.

grunt deploy

Summary of the commands

# install npm dependencies
npm install
# install bower dependencies
bower install

# Run jamstash in dev mode
grunt serve

# See unit-tests' coverage
grunt coverage

# Bump up jamstash's version
# from 4.3.2 to 4.3.3
grunt bump:patch
# from 4.3.2 to 4.4.0
grunt bump:minor
# from 4.3.2 to 5.0.0
grunt bump:major

# Minify jamstash for deployment
grunt

# Build and deploy jamstash on your test server
grunt deploy