As an open source project, Warehouse welcomes contributions of many forms. Contributions can include:
- Bug reports and feature requests
- Pull requests for both code and documentation
- Patch reviews
You can file bugs and submit pull requests on GitHub.
When in doubt, refer to PEP 8 for Python code.
Every code file must start with the boilerplate notice of the Apache License.
SQL statements should use uppercase statement names and lowercase names for tables, columns, etc. If a SQL statement must be split over multiple lines it should use
query = \ """ SELECT * FROM table_name WHERE foo != 'bar' """
Furthermore, you MUST use parametrized queries and should use the named interpolation format (%(foo)s) instead of the positional interpolation format (%s).
Warehouse development requires Python3.4 and the installation of several external non-Python dependencies. These are:
- PostgreSQL 9.2+
- Compass (used only for design development)
- Grunt (used only for design development)
Once you have all of the above you can install Warehouse, all of its install dependencies, and the Python development dependencies using:
$ pip install -r dev-requirements.txt
Finally you can setup the project:
$ # Create a Database $ createdb warehouse $ # Install the CIText extension $ psql warehouse -c 'CREATE EXTENSION IF NOT EXISTS citext' $ # Install the UUID extension $ psql warehouse -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"' $ # Migrate the database to the latest schema $ warehouse -c dev/config.yml migrate upgrade head $ # Initialise the ElasticSearch index $ warehouse -c dev/config.yml search reindex $ # Serve Warehouse at http://localhost:9000/ $ warehouse -c dev/config.yml serve
$ # Install Compass $ gem install compass $ # Install Grunt $ npm install
Once you have the dependencies install you can iterate on the theme by editing the files located in warehouse/static/source. After each edit you’ll need to compile the files by running:
If you’re iterating on the design and wish to have the compilation step called automatically you can watch the warehouse/static/source directory for changes and auto-compile by running:
$ grunt watch
This runs the tests with the default Python interpreter and require that the local user has the necessary privileges to create the test database (named warehouse_unittest). This is easy to set up by creating a PostgreSQL user account matching the local user and giving it the CREATEDB privilege.
Alternatively you can create the test database beforehand and set the WAREHOUSE_DATABASE_URL environment variable to point to it. In that case, you have to manually drop the database after running the tests.
You can also verify that the tests pass on other supported Python interpreters. For this we use tox, which will automatically create a virtualenv for each supported Python version and run the tests. For example:
$ tox ... py34: commands succeeded docs: commands succeeded pep8: commands succeeded
You may not have all the required Python versions installed, in which case you will see one or more InterpreterNotFound errors.
If you want to run all of the tests except the ones that do not need the database, you can run:
$ tox -e py34 -- -k "not db"
Use tox to build the documentation. For example:
$ tox -e docs ... docs: commands succeeded congratulations :)
The HTML documentation index can now be found at docs/_build/html/index.html