There are a number of ways to contribute to django-scribbler. If you are interested in making django-scribbler better then this guide will help you find a way to contribute.
You can contribute to the project by submitting bug reports, feature requests or documentation updates through the Github issues.
We are working towards translating django-scribbler into different languages. There are only a few strings to translate so it is a great way to be involved with the project. The translations are managed through Transifex. Please do not submit translate requests/updates to the Github repo.
You can clone the repository from Github:
git clone git://github.com/caktus/django-scribbler.git
However this checkout will be read only. If you want to contribute code you should create a fork and clone your fork. You can then add the main repository as a remote:
git clone email@example.com:<your-username>/django-scribbler.git cd django-scribbler git remote add upstream git://github.com/caktus/django-scribbler.git git fetch upstream
django-scribbler requires a few static libraries which are not included in the repository. Before beginning development you should make sure you have these libraries with:
When making changes to the code, either fixing bugs or adding features, you’ll want to run the tests to ensure that you have not broken any of the existing functionality. With the code checked out and Django installed you can run the tests via:
python setup.py test
Note that the tests require the mock library. To test against multiple versions of Django you can use install and use tox>=1.4. The tox command will run the tests against Django 1.3, 1.4 and the current Git master using Python 2.6.:
# Build all environments tox # Build a single environment tox -e py26-1.3.X
Building all environments will also build the documentation. More on that in the next section.
The JS plugins are tested using the QUnit <http://qunitjs.com/> testing framework. You can run the tests by opening scribbler\tests\qunit\index.html in your browser. You can also run the tests using the PhantomJS <http://phantomjs.org/> headless runner. First install PhantomJS from NPM (requires at least 1.6):
# Install phantomjs from the NPM package npm install phantomjs -g # Run QUnit tests phantomjs scribbler/tests/qunit/runner.js scribbler/tests/qunit/index.html
We’ve added a make command which you can use as well:
This project aims to have a minimal core with hooks for customization. That makes documentation an important part of the project. Useful examples and notes on common use cases are a great way to contribute and improve the documentation.
tox -e docs
from inside the docs/ directory.
The CSS used by django-scribbler is built using LESS. No changes should be made to the scribbler.css directly. Instead changes should be made to the scribbler.less file. After changes are made to scribbler.less you can create the new compressed CSS with the Node based complier. In addition this uses the RequireJS optimizer to inline the required codemirror.css:
# Install less and requirejs from the NPM package npm install less requirejs -g make build-css
The example project uses the client-side LESS compiler to make local development easier.
While it is not often needed for local development, the final released JS is bundled and minified using the same RequireJS optimizer used for the CSS. To build scribbler-min.js you should have the optimizer installed and run:
Code contributions should follow the PEP8 and Django contributing style standards. Please note that these are only guidelines. Overall code consistency and readability are more important than strict adherence to these guides.
# Install jshint from the NPM package npm install jshint -g # Check the scribbler JS jshint scribbler/static/scribbler/js/
This can also be done with the make command:
The easiest way to contribute code or documentation changes is through a pull request. For information on submitting a pull request you can read the Github help page https://help.github.com/articles/using-pull-requests.
Pull requests are a place for the code to be reviewed before it is merged. This review will go over the coding style as well as if it solves the problem intended and fits in the scope of the project. It may be a long discussion or it might just be a simple thank you.
Not necessarily every request will be merged but you should not take it personally if you change is not accepted. If you want to increase the chances of your change being incorporated then here are some tips.
You should also feel free to ask for help writing tests or writing documentation if you aren’t sure how to go about it.
Since the built CSS, JS and other static dependencies are not included in the repository, it is not possible to install django-scribbler directly from Github. If you want to install and unstable version of django-scribbler you have a few options.
While we try to keep the master branch stable, there may be bugs or unfinished work there. It is recommended that you use a stable release of django-scribbler when possible.
The step overview for installing from a local build is:
From the command line this would be:
git clone git://github.com/caktus/django-scribbler.git cd django-scribbler make fetch-static-libs build-css build-js pip install .
Installing from a local build is probably a reasonable solution for a single person wanting to test out the current master or a feature branch in a large project. However, it isn’t a good solution if you want to deploy this to a larger testing environment or multiple computers. The basic steps are more or less the same:
From the command line this would be:
git clone git://github.com/caktus/django-scribbler.git cd django-scribbler make fetch-static-libs build-css build-js python setup.py sdist
This will create a django-scribbler-X.X.X.tar.gz inside a dist/ directory where X.X.X is the current scribbler.__version__. This tar file would then be distributed using your favorite file hosting service (S3, Dropbox, etc). You can then install by using pip:
pip install http://path-to-hostedfile/django-scribbler-X.X.X.tar.gz