2015-07-20 19:29:16 -04:00
|
|
|
# Contributing
|
|
|
|
|
|
|
|
Contributions are welcome and are greatly appreciated! Every
|
|
|
|
little bit helps, and credit will always be given.
|
|
|
|
|
|
|
|
You can contribute in many ways:
|
|
|
|
|
|
|
|
## Types of Contributions
|
|
|
|
|
|
|
|
### Report Bugs
|
|
|
|
|
2016-01-13 12:03:27 -05:00
|
|
|
Report bugs through Github
|
2015-07-20 19:29:16 -04:00
|
|
|
|
|
|
|
If you are reporting a bug, please include:
|
|
|
|
|
|
|
|
- Your operating system name and version.
|
|
|
|
- Any details about your local setup that might be helpful in
|
|
|
|
troubleshooting.
|
|
|
|
- Detailed steps to reproduce the bug.
|
|
|
|
|
|
|
|
### Fix Bugs
|
|
|
|
|
|
|
|
Look through the GitHub issues for bugs. Anything tagged with "bug" is
|
|
|
|
open to whoever wants to implement it.
|
|
|
|
|
|
|
|
### Implement Features
|
|
|
|
|
|
|
|
Look through the GitHub issues for features. Anything tagged with
|
|
|
|
"feature" is open to whoever wants to implement it.
|
|
|
|
|
|
|
|
### Documentation
|
|
|
|
|
2016-03-29 00:55:58 -04:00
|
|
|
Caravel could always use better documentation,
|
|
|
|
whether as part of the official Caravel docs,
|
2015-07-20 19:29:16 -04:00
|
|
|
in docstrings, `docs/*.rst` or even on the web as blog posts or
|
|
|
|
articles.
|
|
|
|
|
|
|
|
### Submit Feedback
|
|
|
|
|
|
|
|
The best way to send feedback is to file an issue on Github.
|
|
|
|
|
|
|
|
If you are proposing a feature:
|
|
|
|
|
|
|
|
- Explain in detail how it would work.
|
|
|
|
- Keep the scope as narrow as possible, to make it easier to
|
|
|
|
implement.
|
|
|
|
- Remember that this is a volunteer-driven project, and that
|
|
|
|
contributions are welcome :)
|
|
|
|
|
2016-01-13 12:03:27 -05:00
|
|
|
## Latest Documentation
|
2015-07-20 19:29:16 -04:00
|
|
|
|
2016-03-29 00:55:58 -04:00
|
|
|
[API Documentation](http://pythonhosted.com/caravel)
|
2015-07-20 19:29:16 -04:00
|
|
|
|
2016-02-27 10:47:56 -05:00
|
|
|
## Setting up a Python development environment
|
2016-01-13 12:03:27 -05:00
|
|
|
|
2016-04-08 20:57:24 -04:00
|
|
|
Check the [OS dependencies](http://airbnb.io/caravel/installation.html#os-dependencies) before follows these steps.
|
|
|
|
|
2016-01-13 12:03:27 -05:00
|
|
|
# fork the repo on github and then clone it
|
|
|
|
# alternatively you may want to clone the main repo but that won't work
|
|
|
|
# so well if you are planning on sending PRs
|
2016-03-30 17:29:04 -04:00
|
|
|
# git clone git@github.com:airbnb/caravel.git
|
2016-01-13 12:03:27 -05:00
|
|
|
|
|
|
|
# [optional] setup a virtual env and activate it
|
|
|
|
virtualenv env
|
|
|
|
source env/bin/activate
|
|
|
|
|
|
|
|
# install for development
|
|
|
|
python setup.py develop
|
|
|
|
|
|
|
|
# Create an admin user
|
2016-03-29 00:55:58 -04:00
|
|
|
fabmanager create-admin --app caravel
|
2015-07-20 19:29:16 -04:00
|
|
|
|
2016-01-13 12:03:27 -05:00
|
|
|
# Initialize the database
|
2016-03-29 00:55:58 -04:00
|
|
|
caravel db upgrade
|
2015-07-20 19:29:16 -04:00
|
|
|
|
2016-01-13 12:03:27 -05:00
|
|
|
# Create default roles and permissions
|
2016-03-29 00:55:58 -04:00
|
|
|
caravel init
|
2016-01-13 12:03:27 -05:00
|
|
|
|
|
|
|
# Load some data to play with
|
2016-03-29 00:55:58 -04:00
|
|
|
caravel load_examples
|
2016-01-13 12:03:27 -05:00
|
|
|
|
|
|
|
# start a dev web server
|
2016-03-29 00:55:58 -04:00
|
|
|
caravel runserver -d
|
2016-01-13 12:03:27 -05:00
|
|
|
|
2016-02-27 10:47:56 -05:00
|
|
|
|
|
|
|
## Setting up the node / npm javascript environment
|
|
|
|
|
2016-03-29 00:55:58 -04:00
|
|
|
`caravel/assets` contains all npm-managed, front end assets.
|
2016-02-27 10:47:56 -05:00
|
|
|
Flask-Appbuilder itself comes bundled with jQuery and bootstrap.
|
|
|
|
While these may be phased out over time, these packages are currently not
|
|
|
|
managed with npm.
|
|
|
|
|
|
|
|
|
|
|
|
### Using npm to generate bundled files
|
|
|
|
|
|
|
|
#### npm
|
|
|
|
First, npm must be available in your environment. If it is not you can run the following commands
|
|
|
|
(taken from [this source](https://gist.github.com/DanHerbert/9520689))
|
|
|
|
```
|
|
|
|
brew install node --without-npm
|
|
|
|
echo prefix=~/.npm-packages >> ~/.npmrc
|
|
|
|
curl -L https://www.npmjs.com/install.sh | sh
|
|
|
|
```
|
|
|
|
|
|
|
|
The final step is to add
|
|
|
|
`~/.node/bin` to your `PATH` so commands you install globally are usable.
|
|
|
|
Add something like this to your `.bashrc` file.
|
|
|
|
```
|
|
|
|
export PATH="$HOME/.node/bin:$PATH"
|
|
|
|
```
|
|
|
|
|
|
|
|
#### npm packages
|
|
|
|
To install third party libraries defined in `package.json`, run the
|
2016-04-11 18:39:50 -04:00
|
|
|
following within the `caravel/assets/` directory which will install them in a
|
2016-02-27 10:47:56 -05:00
|
|
|
new `node_modules/` folder within `assets/`.
|
|
|
|
|
|
|
|
```
|
|
|
|
npm install
|
|
|
|
```
|
|
|
|
|
2016-03-29 00:55:58 -04:00
|
|
|
To parse and generate bundled files for caravel, run either of the
|
2016-02-27 10:47:56 -05:00
|
|
|
following commands. The `dev` flag will keep the npm script running and
|
|
|
|
re-run it upon any changes within the assets directory.
|
|
|
|
|
|
|
|
```
|
|
|
|
# Compiles the production / optimized js & css
|
|
|
|
npm run prod
|
|
|
|
|
|
|
|
# Start a web server that manages and updates your assets as you modify them
|
|
|
|
npm run dev
|
|
|
|
```
|
|
|
|
|
|
|
|
For every development session you will have to start a flask dev server
|
|
|
|
as well as an npm watcher
|
|
|
|
|
|
|
|
```
|
2016-03-29 00:55:58 -04:00
|
|
|
caravel runserver -d -p 8081
|
2016-02-27 10:47:56 -05:00
|
|
|
npm run dev
|
|
|
|
```
|
2016-01-13 12:03:27 -05:00
|
|
|
|
|
|
|
## Testing
|
2015-07-20 19:29:16 -04:00
|
|
|
|
|
|
|
Tests can then be run with:
|
|
|
|
|
2016-05-03 15:45:38 -04:00
|
|
|
./run_tests.sh
|
2015-07-20 19:29:16 -04:00
|
|
|
|
|
|
|
Lint the project with:
|
|
|
|
|
2016-03-16 11:23:40 -04:00
|
|
|
# for python changes
|
2015-07-20 19:29:16 -04:00
|
|
|
flake8 changes tests
|
|
|
|
|
2016-03-16 11:23:40 -04:00
|
|
|
# for javascript
|
|
|
|
npm run lint
|
|
|
|
|
2015-07-20 19:29:16 -04:00
|
|
|
## API documentation
|
|
|
|
|
|
|
|
Generate the documentation with:
|
|
|
|
|
|
|
|
cd docs && ./build.sh
|
|
|
|
|
2016-03-05 15:41:22 -05:00
|
|
|
## CSS Themes
|
2016-05-02 13:50:23 -04:00
|
|
|
As part of the npm build process, CSS for Caravel is compiled from `Less`, a dynamic stylesheet language.
|
2016-03-05 15:41:22 -05:00
|
|
|
|
2016-03-29 00:55:58 -04:00
|
|
|
It's possible to customize or add your own theme to Caravel, either by overriding CSS rules or preferably
|
2016-05-02 13:50:23 -04:00
|
|
|
by modifying the Less variables or files in `assets/stylesheets/less/`.
|
2016-03-05 15:41:22 -05:00
|
|
|
|
2016-05-02 13:50:23 -04:00
|
|
|
The `variables.less` and `bootswatch.less` files that ship with Caravel are derived from
|
2016-03-05 15:41:22 -05:00
|
|
|
[Bootswatch](https://bootswatch.com) and thus extend Bootstrap. Modify variables in these files directly, or
|
|
|
|
swap them out entirely with the equivalent files from other Bootswatch (themes)[https://github.com/thomaspark/bootswatch.git]
|
2015-07-20 19:29:16 -04:00
|
|
|
|
|
|
|
## Pull Request Guidelines
|
|
|
|
|
2016-03-05 15:41:22 -05:00
|
|
|
Before you submit a pull request from your forked repo, check that it
|
2015-07-20 19:29:16 -04:00
|
|
|
meets these guidelines:
|
|
|
|
|
|
|
|
1. The pull request should include tests, either as doctests,
|
|
|
|
unit tests, or both.
|
|
|
|
2. If the pull request adds functionality, the docs should be updated
|
2016-03-05 15:41:22 -05:00
|
|
|
as part of the same PR. Doc string are often sufficient, make
|
2015-07-20 19:29:16 -04:00
|
|
|
sure to follow the sphinx compatible standards.
|
|
|
|
3. The pull request should work for Python 2.6, 2.7, and ideally python 3.3.
|
2016-05-02 13:50:23 -04:00
|
|
|
``from __future__ import`` will be required in every `.py` file soon.
|
2015-07-20 19:29:16 -04:00
|
|
|
4. Code will be reviewed by re running the unittests, flake8 and syntax
|
|
|
|
should be as rigorous as the core Python project.
|
|
|
|
5. Please rebase and resolve all conflicts before submitting.
|
2016-05-02 13:50:23 -04:00
|
|
|
|
|
|
|
|
2016-05-20 14:05:28 -04:00
|
|
|
## Translations
|
2016-05-02 13:50:23 -04:00
|
|
|
|
|
|
|
We use [Babel](http://babel.pocoo.org/en/latest/) to translate Caravel. The
|
|
|
|
key is to instrument the strings that need translation using
|
|
|
|
`from flask.ext.babelpkg import lazy_gettext as _`. Once this is imported in
|
|
|
|
a module, all you have to do is to `_("Wrap your strings")` using the
|
|
|
|
underscore `_` "function".
|
|
|
|
|
|
|
|
To enable changing language in your environment, you can simply add the
|
|
|
|
`LANGUAGES` parameter to your `caravel_config.py`. Having more than one
|
|
|
|
options here will add a language selection dropdown on the right side of the
|
|
|
|
navigation bar.
|
|
|
|
|
|
|
|
LANGUAGES = {
|
|
|
|
'en': {'flag': 'us', 'name': 'English'},
|
|
|
|
'fr': {'flag': 'fr', 'name': 'French'},
|
|
|
|
'zh': {'flag': 'cn', 'name': 'Chinese'},
|
|
|
|
}
|
|
|
|
|
|
|
|
As per the [Flask AppBuilder documentation] about translation, to create a
|
|
|
|
new language dictionary, run the following command:
|
|
|
|
|
|
|
|
pybabel init -i ./babel/messages.pot -d caravel/translations -l es
|
|
|
|
|
|
|
|
Then it's a matter of running the statement bellow to gather all stings that
|
|
|
|
need translation
|
|
|
|
|
|
|
|
fabmanager babel-extract --target caravel/translations/
|
|
|
|
|
|
|
|
You can then translate the strings gathered in files located under
|
|
|
|
`caravel/translation`, where there's one per language. For the translations
|
|
|
|
to take effect, they need to be compiled using this command:
|
|
|
|
|
|
|
|
fabmanager babel-compile --target caravel/translations/
|