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 "1.3" and "1.4". The higher number, i.e. "1.4", is the "default" branch, and "1.3" is the "maintenance" branch. The movement to a new pair of major branches spans around 12-18 months. 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!
GitHub
SQLAlchemy uses Github for bug reporting and issue tracking, Discussions, Wiki pages, and public source code access.
Reporting Bugs
Bugs are reported using GitHub.
We greatly prefer that usage problems are reported as Github Discussions first, and not as issues. As issues are identified from the description of the problem, SQLAlchemy developers will open issues to be fixed as needed.
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.
For links to current IRC / chat areas, see Real-time channels.
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 Github Discussions 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 :).
