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

• Development Community
• Source Access
• Pull Requests
• Testing
• Continuous Integration
• Documentation
• Coding Guidelines
• Development Environment

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

Development Community

Where can you find the Developers of SQLAlchemy ?

The Developers of SQLAlchemy kindly request all people participating inthese channels respect theCode of Conduct whenseeking or providing support.

• Github Discussions
• TheGithub 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 thesqlalchemy/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 theScheduled Developer Meetings. Gitter based support is available via thesqlalchemy/community Gitter room; more information on this is available on thesupport page.

Scheduled Developer Meetings

A real-time virtual meeting of core developers and contributers occurs in thesqlalchemy/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 usingGit.The primary public repository is atGitHub:

• GitHub:https://github.com/sqlalchemy/sqlalchemy/

  
  git clone https://github.com/sqlalchemy/sqlalchemy.git

Pull Requests

Pull requests are submitted to the GitHub repository athttps://github.com/sqlalchemy/sqlalchemy. Onceaccepted for review, assuming the pull request is altering the code itself andnot just correcting documentation issues, code review occurs within our Gerritsystem athttps://gerrit.sqlalchemy.org where wecan review, modify, and run it through continuous integration tests with a highdegree of control and collaborative ability. The pull request will be closedwith a link to the review in Gerrit. Pull requests for code changes are nevermerged directly.

Please note theGuidelines for Pull Requests which modifysource code (e.g. not just documentation):

• It is preferred to submit an issue in the issue tracker before submitting apull request, particularly for major changes.It is a frequent occurence that pull requests submitted either don't describewhat problem they intend to solve, or they solve the problem in an inappropriateor sub-optimal way. Having a bug or feature issue opened ahead of timewill allow us to to understand the use case and discuss the best approachbefore the contributor makes the effort to write the code and tests.
• Always include tests with the change in code - SQLAlchemy does notcommit changes to code without a corresponding test - every line of code thatisn't tested is technically a bug in itself. When a pull request is submittedwithout tests, itcannot be merged until a test is written. It isextremely common that we receive a pull request that is one line long,yet we need to write many dozens of lines to test it, since99% of the workfor any code change is writing the tests.Please don't submitone-liner PRs without tests. Only submit acompletebug report for code changes where you aren't able to provide tests.
• Please follow up for requests for changes on the pull request, as wellas subscribe to the Gerrit review to receive comments. - Pull requests whererequested changes are not responded towards will be closed.
• Please make sure you are configured to run the currentDevelopment 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 isto be proficient in running the tests, and in the ideal case, being able towrite tests. SQLAlchemy has over many thousands of tests which span in focusfrom unit to integration, and a full continuous integration run over multiplePython versions and database backends runs well overtwo hundred thousandindividual tests.By far the largest scope of development work, both on theexisting codebase as well as when any new feature or fix is beingimplemented, is in writing complete tests. The tests for a particular changeor feature are generally five to ten times as many lines of code as thecode for the actual behavior. They also can be much more difficult towrite than the actual feature, often requiring a wide variety of difficult-to-anticipate variants on the target behavior, injection of behavior fortesting purposes, interception of generated SQL, events, or elements of DBAPImessaging.

Tests are run usingpy.test.A comprehensive guide to running the tests is present in the fileREADME.unittests,which is present in the source distribution. This file explains in detail howtests can be run across many scopes, including how to run for specific databasesand 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 toPEP8. 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 withself orcls. The test suite has standard fixtures which help greatly with this process, undertest/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-onlyJenkins interface is available athttps://jenkins.sqlalchemy.org.

Documentation

Documentation builds usingSphinx. 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 toPEP8 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 underSphinx.
• No feature or bug fix is ever committed without fullunit tests to as much a degree as possible.
• Please make sure you are configured to run the currentDevelopment 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 thepre-commit framework. `pre-commit` can be installed by runningpip install pre-commit.
• Source code is formatted using Python Software Foundation'sblack. `black` can be installed by runningpip install black, however `pre-commit` should automatically install it in most situations.

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