Front-End Developement

CherryMusic switched to using Bootstrap 3 which in turn uses less-css. less-css is basically css with macros and is normally compiled offline and then deployed with the web-application. We went with a hybrid approach; For the end-user we compile and minify everything. This is the default front-end. For developing, we have a raw and self-compiling version, so we can keep up the developement speed. We've chosen the same approach for the javascript.

The deployment script (deploy.py) compresses the javascript and compiles the less-css, so cherrymusic will load more quickly for the end-users. This deployment script uses the res/devel.html as input and creates res/main.html as output. If you open cherrymusic in the browser, you get the compiled version as default. (you'll notice that all js files are replaced by only one file called cherrymusic.dist.js) You should never make changes to the res/main.html since it is auto-generated, so any changes to the main.html will be overwritten by the deployment script. Furthermore, there are some mustache HTML templates that might be of interest which are used mostly in res/mediabrowser.js to render search results.

If you want to make any changes to the frontend you should append a GET parameter devel=True to your URL, e.g. localhost:8080/?devel=True. This will give you the undeployed version of CM, which contains all the JS files and less-css imports and the less-css compiler. Since the less compiler is distributed with CM, this allows for quick changes. We have a not-so-strict naming scheme for all the less-css. If you're curious, the modded parts of bootstrap are: res/bootstrap3/less/cherrymusic.less, res/bootstrap3/less/jplayer.less and res/bootstrap3/less/mediabrowser.less

The deployment script deploy.py requires:

node.js and the less compiler lessc
jsmin
python3

jsmin and lessc have to be in your $PATH.

You can make changes, test them and submit them without having installed the deploy requirements using the devel=True GET parameter.

For the location of files and resources, check out the [CREATE PAGE: Package Structure] page.

Back-End Development

The CherryMusic server code resides in the cherrymusicserver package. For an overview of CherryMusic's files and resources, see the [CREATE PAGE: Package Structure] page.

Testing

Dependencies

To run tests, the following modules are required:

nose
mock
unittest2 (Python 2.6)
coverage (optional)

Running tests

The runtests script is responsible for running the test-suite (on unix-y systems). If the coverage module is installed, a minimum coverage requirement is enforced to ensure test coverage does not decrease.

 Usage: runtests [-d OUTPUT_DIR] [TARGET]

 -d OUTPUT_DIR   if given, write HTML coverage report to this directory, 
                 creating it if necessary.

 TARGET          if given, only test the module "cherrymusicserver.TARGET" 
                 by running "cherrymusicserver.test.test_TARGET". Full 
                 coverage is required in this case.

As an alternative, nosetests can be run in the project directory. This is what our travis setup does.
There is also the [pre-commit] script, which can be used as a commit hook to automatically run tests before a commit gets created. To use it, place an executable symlink of the same name into .git/hooks.

Continuous Integration

Automatic Tests

travis-ci tests certain branches after commits to github. .travis.yml contains the relevant configuration. There are browser plugins to display project build status while browsing github. Add [ci skip] to the commit message to skip a CI build for a commit.

Coverage Reports

Our travis builds are tracked and analyzed for test coverage by coveralls.io. Again, .travis.yml is relevant.

RESTful Interface definition (in developement!)

[CREATE PAGE: RESTful Interface definition ]

Release Checklist

Here's the recommended way to create a new release from the current devel branch.

Create release branch

$ git checkout devel && git checkout -b release

Test
```
$ ./runtests
```
Bump the version
- VERSION in cherrymusicserver/__init__.py
- add CHANGES
Create the release commit
```
$ git commit --all -m "version X.Y.Z"
```
Create annotated tag with release number
```
$ git tag -a "X.Y.Z" [-m <MESSAGE>]
```

Merge into devel and master, then push.

$ git checkout devel && git merge release \
&& git checkout master && git merge --ff-only release \
&& git push --tags origin && git branch -d release

Useful links

API

designing RESTful web services

CherryMusic

Contents