A guide to getting involved with SQLAlchemy.
- Developer Roster
- Development Community
- Source Access
- Pull Requests
- Continuous Integration
- Coding Guidelines
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.
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-develIRC 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.
- Bitbucket: https://bitbucket.org/zzzeek/sqlalchemy/
git clone https://bitbucket.org/zzzeek/sqlalchemy.git
- Github: https://github.com/zzzeek/sqlalchemy
git clone https://github.com/zzzeek/sqlalchemy.git
Major release branches are maintained using branches. For example, to get at the 0.9 branch, the tag
git clone -b rel_0_9 https://github.com/zzzeek/sqlalchemy.git sa08
The pull request is a widely understood system of submitting patches for review. SQLAlchemy accepts pull requests through GitHub as well as Bitbucket; GitHub is preferred.
To propose a code change, please submit a pull request to Github.
While we accept pull requests through the usual channels, our current process of reviewing and integrating them is a little unusual; new pull requests are now closed (or on BitBucket marked as "declined") upon initial review without being merged at all; instead, the patch itself is imported into 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. A comment on the pull request is added, providing a direct link to the Gerrit review as well as a direct link to fully register into Gerrit. Gerrit logins are provided via GitHub authorization.
It's not strictly necessary to learn to use Gerrit though it is extremely helpful. At the very least, make sure you set up your email address via the register link so that you receive notifications of comments on the change.
If you do use Gerrit, we strongly recommend using the git-review tool provided by the Openstack project. Pushing to Gerrit is vastly easier using this tool.
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
cls. The test suite has standard fixtures which help greatly with this process, under
- 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 IntegrationThe SQLAlchemy project uses Jenkins for continuous integration. Our read-only Jenkins interface is available at https://jenkins.sqlalchemy.org.
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.
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.
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.