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.

Participate

Project Status

A key to participation is being tuned in to the project's current status. The current released version of SQLAlchemy is always at the top of the homepage on the right hand side. Usually there are two branches released at a time, such as "0.6" and "0.7". The higher number, i.e. "0.7", is the "default" branch, and "0.6" is the "maintenance" branch. The movement to a new pair of major branches spans around 12-18 months. Releases within each branch are between one and two months apart. At some point there will be a 1.0 release. But our approach of moving slowly and steadily has so far been very beneficial to the project, allowing great strides in architecture and usage before a larger pool of new users is taken on.

The overall status of development can be gleaned by viewing the GitHub project page.. We try to assign all bugs and new features to a specific version, which are linked to milestones. A specific number, like "0.6.8", means we'd like to get the ticket completed as of that version (though this is not always guaranteed). An "open ended" number like "0.7.xx" means the ticket is "in the queue", but is not determined to be part of any specific version. A lot of these tickets are of lower priority, some very involved and tedious as well, and are pushed along major releases, in some cases several times. You can help out with some of them!

Major new developmental initiatives are also discussed on the development list. This list has historically been a little dead but we hope to revive it. New releases are always announced on the main mailing list, and more recently on the SQLAlchemy Blog, recently upgraded to allow a higher volume of posts. Occasional more in-depth posts can also be found at techspot.zzzeek.org.

GitHub

SQLAlchemy uses Github for bug reporting and issue tracking, Wiki pages, and source browsing. Sign up for a GitHub account in order to participate in issues.

Reporting Bugs

Bugs are reported using GitHub using the Issues tracking system.

It is common these days for issues reported on Github that are not really bugs but are instead usage questions. In the past we've tried to discourage the use of this style of reporting, however as it's prevalent on Github and Github has a very open-ended tagging system, we will tag such issues as "question" and answer them normally, however note we still welcome user questions on the mailing list as has been the case for many years.

When reporting a behavioral (non-documentation) bug we ask that you:

  • Create a succinct test case which reproduces the issue. This needs to be a script that we can actually run - so it should not require any imports that the SQLAlchemy developers don't have access to, and in the vast majority of cases should not have any imports outside of SQLAlchemy itself. It needs to include whatever table definitions and data are required to reproduce the issue. While we have access to most database backends, SQLite is preferred unless the issue is specific to a certain backend.

    The guide we use for this is How to create a Minimal, Complete, and Verifiable example on StackOverflow. Please give it a read.

  • At the very least, if code examples are not feasible, please include complete stack traces for all exceptions being observed. Nothing is more vague than an exception message without a stack trace.
  • Tell us exactly what version of SQLAlchemy the issue is being observed with, as well as details about the database in use as well as the exact driver (e.g. Python DBAPI) being used.
  • Please respond to further questions asked on the issue. If we can't get the additional information we need, we will usually have to close the issue.

Reporting Security Issues

SQLAlchemy participates in the Tidelift security infrastructure for reporting potential vulnerabilities reponsibly. Please follow the guidelines at Tidelift security in order to report a security issue. Security-related issues in SQLAlchemy are extremely rare, and there have only been three CVEs reported in a fourteen year period. Nevertheless, we would ask that you please do not file CVEs without emailing us first, so that proper disclosure steps may be taken.

User Assistance

SQLAlchemy always needs people to help answer questions, particularly from new users.

The Mailing list is active every day, and can sometimes receive a dozen new users in one week. Help with fielding new users and questions on the list is always appreciated ! Regular users can also volunteer to help with approval of new posters.

The IRC channel #sqlalchemy on Libera is similarly busy most days. There's a core set of "regulars" who are pretty friendly, and more helpers are always welcome.

SQLAlchemy places great emphasis on polite, thoughtful, and constructive communication between users and developers. Rudeness, personal insults, or brusque answers are never appropriate, even for users with unreasonable requests. See our Code of Conduct for a full statement. We also try to ensure that no message on the mailing list goes unanswered, even if the answer is simply to politely direct the user towards the appropriate section of documentation. The core SQLAlchemy developers would like to encourage all users to help with this task - if you see a very basic question sitting on the list for a few days, that's us hoping you'll respond to it ! You have our permission :).

Publicizing SQLAlchemy

We love for people to spread the word about SQLAlchemy. Some common venues:

  • Twitter - we get a lot of comments good and bad via Twitter - if the tweet contains "sqlalchemy" or a link to the site, it will show up under searches for the term. Expect SQLAlchemy developers to respond to provocative tweets!
  • Blog Posts - Users often write short tutorials or blog posts describing how to achieve something with SQLAlchemy. It all becomes part of the larger collection of knowledge so share freely!
  • User group presentations - lots of users present SQLAlchemy, or an application that SQLAlchemy was instrumental towards, to their local Python group or other software development group. Put your slides up on the web after the presentation!
Next ... Develop