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.

Developer Roster

Modern releases of SQLAlchemy include a core developer list. The names of developers who are currently or have been critical to our progress are in this file, the current version of which can be seen at AUTHORS.

A list of all developers who have ever contributed to SQLAlchemy, even a single patch, is maintained at Contributors.

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. Public repositories are available at Bitbucket and Github:

Changes can be shared with core developers using pull requests to either of these services. Patch files can also be submitted as attachments to Bitbucket issues.

Major release branches are maintained using branches. For example, to get at the 0.8 branch, the tag is called rel_0_8:

git clone -b rel_0_8 https://bitbucket.org/zzzeek/sqlalchemy.git sa08

Downloadable snapshots of the current default and maintenance branches are available on the download page.

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 3000 tests which span in focus from unit to integration. 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.

The tests run using Nose. A comprehensive guide to running the tests is present in the file README.unittests, which is available in the distribution. After downloading the source distribution of SQLAlchemy, this file explains in detail how tests can be run, overall, for specific databases, and specific tests. Ideally, any patch that's given to use via Trac or similar should be tested in the default branch against the full test suite. We of course do this in any case but the patch which takes this into account is always preferable.

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

We run a Jenkins server for continuous integration at jenkins.sqlalchemy.org. A quick overview of how wide a variety of scenarios our tests need to run within can be seen here.

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 a great interest in attracting developers through sprints. Currently there is only one official "sprint" per year at Pycon US. We are in need of assistance for planning these 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.