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¶
- make start-server to start the fake package server, which is used throughout the tests.
- make test to run all tests. Use make unit to only run the unit tests, and make ecukes to only run the integration tests.
- Repeat 2. as long as you need.
- 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.