Contributing to Cask

This document provides guidelines and information on contributing to Cask.

Cask is on GitHub, and a discussion group is available at https://groups.google.com/forum/#!forum/cask-dev.

Testing

Cask comes with a rich set of test cases. When fixing bugs or implementing new features, please add the corresponding test cases as well.

Running tests

  1. make start-server to start the fake package server, which is used throughout the tests.
  2. make test to run all tests. Use make unit to only run the unit tests, and make ecukes to only run the integration tests.
  3. Repeat 2. as long as you need.
  4. make stop-server to stop the fake package server started in 1.

Documentation

Cask includes a comprehensive user guide. Please try to extend it accordingly when you implement new features.

The documentation is written in reStructuredText, using Sphinx and sphinxcontrib-emacs. The former is a generic documentation tool, and the latter extends it with specific support for Emacs Lisp projects.

Setup

To build the documentation locally, you need to go through a little setup first.

Make sure that you have Python 2.7 and virtualenv available. To install virtualenv, use the following command:

$ pip install --user virtualenv

Then add ~/Library/Python/2.7/bin (on OS X) or ~/.local/bin (on other Unix variants) to PATH.

Note

You probably need to install pip first. It is available in the package repositories of most Linux distributions, as python-pip or similar. If pip is not available for your Linux distribution, or if you are using OS X, please follow the instructions to install pip.

Now create a virtualenv for the documentation, and install the requirements:

$ mkdir -p ~/.virtualenvs
$ virtualenv -p python2.7 ~/.virtualenvs/cask
$ pip install -r doc/requirements.txt

Now you are set up to build the documentation.

Building

Now you are ready to build the documentation.

First, switch to the virtualenv and make sure that the requirements are up to date:

$ source ~/.virtualenvs/cask/bin/activate
$ pip install -r doc/requirements.txt

Then you can build the HTML documentation, or verify all links in the documentation:

$ make html  # Build HTML documentation to build/doc/html/
$ make linkcheck  # Check all links in the documentation

Pull requests

If all tests passes, and the documentation builds, please send us a pull request with your changes.

Note

Usually we work on a WIP branch, named vmajor.minor-wip. Your pull request should target this branch, if present. Otherwise just base your pull request on master.