Contributing

Process

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.

Code

When in doubt, refer to PEP 8 for Python code.

Every code file must start with the boilerplate notice of the Apache License.

SQL

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).

Development Environment

Warehouse development requires Python3.4 and the installation of several external non-Python dependencies. These are:

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

Design Development

Warehouse design development uses Compass and Grunt as its asset pipeline. You can install the required dependencies by running:

$ # 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:

$ grunt

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

Running Tests

Warehouse unit tests are found in the tests/ directory and are designed to be run using pytest. pytest will discover the tests automatically, so all you have to do is:

$ py.test

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"

Writing Tests

See Testing for more information about writing tests.

Building Documentation

Warehouse documentation is stored in the docs/ directory. It is written in reStructured Text and rendered using Sphinx.

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