Community Guide

A guide to getting involved with SQLAlchemy.

Develop

This section describes where to find information on development and some tips on getting started.

Development Community

Where do you find the developers ? Three places:

  • The main mailing list is the most common - core devs assist users with issues of all kinds.
  • Developer discussion takes place on the development mailing list, also hosted on Google groups. Anyone can join this list, though we ask that discussion be limited to architectural and developmental issues only.
  • Some development discussion occurs on the #sqlalchemy-devel IRC channel on Freenode. This channel is only for users that are interested in contributing code, tests, documentation, or other developmental resources, and no support issues will be addressed here. IRC-based support is available on the main IRC channel.

Source Access

SQLAlchemy's source code is versioned using Git. The primary public repository is at GitHub:

Pull Requests

Pull requests are submitted to the GitHub repository at https://github.com/sqlalchemy/sqlalchemy. Once accepted for review, assuming the pull request is altering the code itself and not just correcting documentation issues, code review occurs within our Gerrit system at https://gerrit.sqlalchemy.org where we can review, modify, and run it through continuous integration tests with a high degree of control and collaborative ability. The pull request will be closed with a link to the review in Gerrit. Pull requests for code changes are never merged directly.

Please note the Guidelines for Pull Requests which modify source code (e.g. not just documentation):

  • It is preferred to submit an issue in the issue tracker before submitting a pull request, particularly for major changes. It is a frequent occurence that pull requests submitted either don't describe what problem they intend to solve, or they solve the problem in an inappropriate or sub-optimal way. Having a bug or feature issue opened ahead of time will allow us to to understand the use case and discuss the best approach before the contributor makes the effort to write the code and tests.
  • Always include tests with the change in code - SQLAlchemy does not commit changes to code without a corresponding test - every line of code that isn't tested is technically a bug in itself. When a pull request is submitted without tests, it cannot be merged until a test is written. It is extremely common that we receive a pull request that is one line long, yet we need to write many dozens of lines to test it, since 99% of the work for any code change is writing the tests. Please don't submit one-liner PRs without tests. Only submit a complete bug report for code changes where you aren't able to provide tests.
  • Please follow up for requests for changes on the pull request, as well as subscribe to the Gerrit review to receive comments. - Pull requests where requested changes are not responded towards will be closed.

Testing

A critical task for anyone wishing to develop even small features or fixes is to be proficient in running the tests, and in the ideal case, being able to write tests. SQLAlchemy has over many thousands of tests which span in focus from unit to integration, and a full continuous integration run over multiple Python versions and database backends runs well over two hundred thousand individual tests. By far the largest scope of development work, both on the existing codebase as well as when any new feature or fix is being implemented, is in writing complete tests. The tests for a particular change or feature are generally five to ten times as many lines of code as the code for the actual behavior. They also can be much more difficult to write than the actual feature, often requiring a wide variety of difficult-to- anticipate variants on the target behavior, injection of behavior for testing purposes, interception of generated SQL, events, or elements of DBAPI messaging.

Tests are run using py.test. A comprehensive guide to running the tests is present in the file README.unittests, which is present in the source distribution. This file explains in detail how tests can be run across many scopes, including how to run for specific databases and how to select for specific tests.

The tests themselves have been written over the course of many years, and stylistically have evolved. We try to upgrade old tests to newer styles as we become more proficient and advanced in our methodologies, but there are still many tests that are in need of an upgrade. Our current preferred style, keeping in mind that many of our tests are certainly not yet in this style, is as follows:

  • Tests should stick to PEP8. Many older tests currently do not; this is an area in which we welcome new help.
  • Test just one thing. A series of individual assertions are best broken up into individual test methods, rather than one test method with several assertions.
  • Maintain per-test state as local to a test fixture. That is, if a series of tests are all against a specific table structure, the test fixture should prepare the table metadata and associate it with self or cls. The test suite has standard fixtures which help greatly with this process, under test/lib/fixtures.py.
  • Don't test against a database backend if not needed. Many kinds of tests only need to ensure that a particular SQL string is rendered. We have a comprehensive set of fixtures which allow SQL strings to be captured and asserted without any database round trip needed.

Continuous Integration

The SQLAlchemy project uses Jenkins for continuous integration. Our read-only Jenkins interface is available at https://jenkins.sqlalchemy.org.

Documentation

Documentation builds using Sphinx. New developers can be very helpful if they are willing to write new documentation, or to work on current documentation, adding new examples, fixing typos, improving inter-documentation linkage. This is also some of the most important and difficult work for the project. As is the case with testing, good documentation takes up a significantly larger amount of time to create than the feature itself being documented. It's not as fun to write documentation for most developers as it is to write actual code, but a developer who is willing and able to do so is tremendously valuable to the project.

Code Guidelines

We hope to expand this section. For now, some key things to keep in mind:

  • Try to stick to PEP8 as much as possible. Our line width is 78 characters and we tend to break lines on backslashes rather than parenthesis; in particular SQLAlchemy generative queries are most easy to read broken up along backslashes.
  • New features can only be added if they have associated documentation that runs under Sphinx.
  • No feature or bug fix is ever committed without full unit tests to as much a degree as possible.

Sprints

The SQLAlchemy project has an interest in attracting developers through sprints. Currently, there are only occasional sprints typically annually at Pycon US, though not always. We are in need of assistance with planning, organizing and running sprints such that new developers are well prepared to contribute and learn about SQLAlchemy. Contributors who are interested in mentoring new developers at sprints or hosting other sprints during the year are encouraged to contact the developers, we would love to have more assistance in this area.