tempbottle / spine

Lightweight MVC library for building JavaScript applications

Spine


Spine is a lightweight MVC library for building JavaScript web applications. Spine gives you structure and then gets out of your way, allowing you to concentrate on the fun stuff: building awesome web applications.

Spine is opinionated in its approach to web application architecture and design. Spine's architecture complements patterns such as de-coupled components and CommonJS modules, markedly helping with code quality and maintainability.

The library is written in CoffeeScript, and though it doesn't necessarily require CoffeeScript to develop applications - you can use whichever language you're most familiar with or prefer - the documentation and some associated tools like Hem and spine.app cater to those who prefer CoffeeScript's syntax.

Learn it

Documentation is often incomplete or just lies waiting to happen. Approachable source code reduces knowledge dependencies. This is an area where Spine really excells compared to other MVC frameworks. Spine is tiny; the core library comes in at less than 700 lines of CoffeeScript code. It is written in such a way to prefer readability over terseness or clever tricks, and it is small enough that within a rather small timeframe you can understand how all the pieces work together. Expertise is achievable within days or weeks rather than months or years. For these reasons, remaining lightweight and simple is fundamental to Spine.

For documentation, usage, and examples, see: spinejs.com

The test suite can also occasionally provide additional useful examples, especially if you are looking for non-coffeescript examples.

Contributing

Reporting issues

To file a bug report, please visit the GitHub issues page. It's great if you can attach code (test cases and fixes for bugs, and test cases and a proposed implementation for features), but reproducible bug reports are also welcome.

For support or help with using spine please use the Spine Google Group and/or StackOverflow rather than opening an issue on Github. If you post in those places you are more likely to get more people to chime in, and others can benefit from it more readily.

Cloning master and running the test suite

To get started contributing to Spine, first clone the repository and make sure you can run the test suite. If you're not familiar with Git, visit the Git homepage to download Git for your platform.

First, clone the repository:

$ git clone git://github.com/spine/spine.git
$ cd spine

Next, You will need node and npm to pull in the testing libraries. Once you're all set with those then from within the Spine repo directory run

$ npm install .

This should bring in Jasmine, Coffeescript, and a minimalist local server for running the tests a browser. You can also simply open test/index.html in a browser to run the Jasmine test suite for spine core. If you see all the tests passing, you're ready to contribute! A known issue is that some of the routing tests will fail if you are simply using a file:// protocol in the browser. This has to do with browser security. You can avoid this by running the local server, $ npm start. Alternatively you can use a server like Apache or Nginx to serve the test files to the browser.

If you have phantom.js available then a script is included to make running tests even slicker!

$ npm test

Contributing to the Spine documentation

Perhaps the easiest way to get started with contributing is through the docs. If you find typos, bugs, or omissions in the docs, please submit a pull request to fix. The Spine website spinejs.com, which is the primary documentation, is a very simple rails app spine.site. You don't need to know Rails or Ruby to contribute. The vast majority of it is in Markdown

Contributing to the Spine code

This recommended contribution process is based on the Ruby on Rails contribution guide. In general, please include tests with new features or bugfixes, work in a feature branch until you're ready to submit or discuss your code, then fork the repository, push to your fork, and issue a pull request.

CoffeeScript

When submitting a pull request for code, please submit in CoffeeScript. Building the effected js files is required for testing sake, but submitting those js files is optional.

Assuming you have Node.js and npm already installed then proceed by installing local dev dependencies:

$ npm install .

Then use the provided build scripts to compile your CoffeeScript files:

$ cake build
$ cake watch

These tasks use a locally installed copy of CoffeeScript to ensure all contributors use the same version of the compiler.

Git

Let's say I'm going to submit a patch to add someFeatureFix:

$ git checkout dev

Feature branches should start from dev not master. If you branch off of, or do builds on the master branch you will get CoffeeScript source map files, which are cool, but tend to ruin automatic merges with git.

$ git checkout -b someFeatureFix
$ vim test/...
  # (...add tests...)
$ cake watch
  # (...this should recompile and changes you make in your CoffeeScript...)

-- figure out what spine module your changes belong in
$ vim src/spine.coffee
or
$ vim src/[otherSpineComponent].coffee
  # (...add the feature/fix...)
$ open test/index.html
  # (...make sure tests run for each component that was changed...)
  # (...test in other browsers with various jquery versions if you feel like there is risk... )
$ git commit -m "Add Some Feature Fix"

Then, fork the Spine repository, and push your branch to your fork:

$ git remote add <your user name> [email protected]:<your user name>/spine.git
$ git push <your user name> someFeatureFix

Finally, issue a pull request from inside the GitHub interface to the dev branch of spine, and your contribution is ready for consideration, discussion, and (hopefully) merging in!