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 current practices for external contributions.

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 throughout 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. Gitter based support is available via the sqlalchemy/community Gitter room; more information on this is available on the support page.

Source Access

SQLAlchemy's source code is versioned using Git. The primary public repository is at GitHub:

Pull Requests and AI Contributions

The SQLAlchemy project and its related projects Alembic, Mako, dogpile.cache accept PRs only on a limited, pre-approved basis. Our projects are open to outside contributions as pull requests for significant, meaningful new use cases, refactorings, or fixes which have been thoroughly discussed and agreed upon either in a discussion, or an issue, amongst humans. Like everyone else, we receive a lot of issue comments, discussions etc. where the content is obviously LLM generated. We can't really prevent that from happening, however people seeking to make meaningful contributions to SQLAlchemy in the form of pull requests need to interact with us as humans, not robots.

In the age of large language models (LLMs), the SQLAlchemy project receives a significant influx of AI generated issues which are created with the goal of submitting AI generated pull requests. These issues are mostly of a similar nature; either an edge-case issue in SQLAlchemy that was identified by an LLMs which otherwise went unnoticed for years, or an existing old issue only needing a small fix. The PRs themselves, prior to our enacting of submission gates, followed a wide range of quality levels, testing approaches, and architectural novelty. All of this variation in what we receive, as well as that we have to interact over the course of days with a remote author in order to get changes made, adds significant burden to the tasks of human review and communication; while all the while, the other end of the pull request is simply someone's LLM responding to us - an interaction we could instead have with our own LLMs much more easily.

All patches to SQLAlchemy are human reviewed, and we maintain strict architectural standards even for code that's entirely AI submitted. The truth is that for this influx of small, edge case issues, it's much more efficient for us to use our own LLMs to construct and submit patches internally, where we can prompt it the way we want up front and handle followup revisions quickly and accurately. Reviewing and revising what comes from random contributors is actually more work.

The process for pull requests is then as follows:

  1. a github issue describing the bug or use case must be posted first. We **strongly** prefer that outside contributors start by posting a Github discussion, which we can escalate to a real issue or issues as needed.
  2. Once the github issue is posted, pull requests are not accepted unless the label "open for pull requests" is added by the maintainers to the issue.
  3. Pull requests that are submitted which don't reference an issue, or reference an issue that does not have the "open for pull requests" label, are automatically closed.
  4. If an issue is labeled as "open for pull requests", PR's 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.
  5. The vast majority of issues that are easily addressible by a large language model are not open for pull requests. We need to assign our own LLMs and humans to each patch regardless, and it's faster for us to keep such patches on our side entirely.

The upshot of the above is that the SQLAlchemy project is not interested in small PRs done by someone's robots; we can do that ourselves. Thoughtful human contributors seeking meaningful engagement with the project are as always welcome.

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.