Contributing¶
We are happy to see patches and improvements with Grappelli. But please keep in mind that there are some guidelines you should follow.
To file an issue with Grapelli, see contributing on github.
Requirements¶
For working with Javascript and CSS, you need Node, Ruby, Grunt, Sass and Compass. In order to update the documentation, Sphinx and the Sphinx RTD Theme have to be installed. Finally, you should install flake8 when working with python files.
It’s out of the scope of this tutorial to go into details, but you should find lots of useful references on how to install these dependencies.
Node is needed for Grunt, Ruby for Sass/Compass:
brew install node
brew install ruby
Now you are able to install Grunt and Compass (Sass is automatically installed with Compass):
npm install -g grunt-cli
gem install compass
Change to the root of your grappelli installation, where package.json
and Gruntfile.js
are located and install the Grunt dependencies:
npm install
Start your virtual environment and install the python dependencies:
pip install sphinx
pip install sphinx-rtd-theme
pip install flake8
Branches¶
Please commit to the stable branch of a specific Grappelli version and do not use the master branch. For example, in order to send pull-requests for Grappelli 2.7, use the branch stable/2.7.x.
Python¶
When working with python files, please refer to the Django Coding Guidelines. Grappelli includes a grunt task which checks for coding errors (you should always use this task if you update .py files):
grunt flake8
Note
flake8 has to be installed in order for this task to work.
Javascripts & Stylesheets¶
If you change any of the Grappelli javascripts, you need to jshint the files and create grappelli.min.js:
grunt javascripts
When working with CSS (which is .scss in our case), you have to compile with:
grunt compass
Documentation¶
If you update documentation files, there’s a grunt task for building the html files (this is not needed with a pull-request, but you might wanna check your updates locally):
grunt sphinx
Watch¶
You can use grunt watch
or just grunt
in order to check for live update on js/scss files as well as the documentation and run the necessary grunt tasks in the background while working.