Community Guide

A guide to getting involved with SQLAlchemy and its associated projects.

While these sections may be written to address developers of the core SQLAlchemy project, the various guidelines, especially the Code of Conduct, apply to all projects hosted under the SQLAlchemy organization's repository.

Develop

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

Development Community

Where can you find the Developers of SQLAlchemy ?

The Developers of SQLAlchemy kindly request all people participating in these channels respect the Code of Conduct when seeking or providing support.

  • Github Discussions
    • The Github Discussions forum is the most common - core devs assist users with issues of all kinds. All SQLAlchemy users and third-party library authors are encouraged to seek support here.
  • Real-Time Communication
    • Development discussion continually occurs in the sqlalchemy/devel Gitter room througout the week. Discussion in this room is intended for users who are interested in contributing code, tests, documentation, or other developmental resources. This channel is the current preferred real-time discussion medium for SQLAlchemy contributors and hosts the Scheduled Developer Meetings. Gitter based support is available via the sqlalchemy/community Gitter room; more information on this is available on the support page.

Scheduled Developer Meetings

A real-time virtual meeting of core developers and contributers occurs in the sqlalchemy/devel Gitter room on a regular basis. This meeting is intended to be held weekly at a regular time, but this may vary based on the availability of required members. In advance of every meeting, the room will contain a link to a document containing the Date, Time and Agenda for the next scheduled meeting; currently this appears in the "Subject Line" or "Title" of the room. These meetings and their records are open to the public. Users who are interested in contributing code, tests, documentation, or other developmental resources are encouraged to attend.

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.
  • Please make sure you are configured to run the current Development Environment requirements, which will help ensure your PRs pass automatic tests.

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.
  • Please make sure you are configured to run the current Development Environment requirements, which will help ensure your PRs pass automatic tests.

Development Environment

The SQLAlchemy project has recently standardized to adopting a few conventions during development, most of which can be automatically enforced by a properly configured development environment.

  • Source code formatting and other utilities are automatically applied using hooks in the pre-commit framework. `pre-commit` can be installed by running pip install pre-commit.
  • Source code is formatted using Python Software Foundation's black. `black` can be installed by running pip install black, however `pre-commit` should automatically install it in most situations.

TLDR; please ensure pre-commit is installed in your environment before beginning work on a Pull Request.