• Current Release Series (2.0)
• Beta release (2.1)
• Develoment Access
• License
• Version Numbering
• Release Status

Point Releases

Point releases are the most common release series, occurring as often as every fewweeks or less for active projects. A point releaseshouldalways be fully compatible for any project to move to thatversion with no changes, given a particular major/minor series.. This means, if aproject is on version 1.2.3 of SQLAlchemy, in the ideal case this projectshould be able to upgrade directly to the latest 1.2.x series, such as 1.2.19without the need to move to interim releases.

A point release includes three categories of change:

• Bug fixes - the primary purpose of a point release is to release fixes for bugswith no backwards incompatible changes being made. A bug fix that isdetermined to be too risky towards backwards compatibility will instead bepushed into a minor release.
• Use case additions - A "use case" is a category of change that falls inbetween a "bug fix" and a "feature", and they most often apply to support fornew database capabilities. As new database capabilites are created orrequested by users continuously, and usually refer to particular datatypes orsmall SQL syntaxes, these capabilities are often added to a point releaseprovided they don't break backwards compatibility within SQLAlchemy or withinAlembic migrations. Larger use case additions are released within a minorrelease.
• Small feature additions - As the release cycle for point releases are everyfew weeks, whereas the release cycle for a minor release is usually at least ayear or more, feature additions that have no impact on any current code orAPis will often be included in point releases; an example would be theability to createsub-options on an ORM loader option.

Note that while point releases are the most conservative and frequent releasestream, it is always possible that an accidental regression may be introduced.It is advised that projects always fully test their software including the useof test suites and/or staging environments when upgrading to a new version ofany SQLAlchemy organization software.

Significant Minor Releases

Minor releases in SQLAlchemy are actually kind of "major" events as theytypically take a year to produce; for related projects, minor releasesmay come less frequently. We may refer to them asSignificant Minor Releasesto indicate that they are major events, while at the same time not conflatingthem with the name "major" as typically refers to the leftmost digit in theversioniong scheme. A change in minor releasemeans that the project includes changes that aretypically backwards compatiblewithin the range of not-previously-deprecated APIs and current Python versions,with some risk of non-backwards compatibility, particularly within SQLAlchemyitself; this risk is usually unavoidable due to the nature of the changes.

For this reason, a "Significant Minor Release" is not really that "minor" for SQLAlchemy itself, andthere is alwaysanextensive migration notes section describing in great detailevery API adjustment and behavioral change which may need to be identified.For other projects, a minor release typically refers to changes in Python versionsupport, such as dropping support for Python 2.6, or Alembic dropping support forSQLAlchemy 0.9; a general idea of what's new is in the changelog.

A Significant Minor Release, particularly in SQLAlchemy itself, will include:

• Major new features - new API features and capabilities, as well as structuraland performance improvements, are part of every minor release forSQLAlchemy itself and very often for related projects. These additions aregenerally fully backwards-compatible, however as they often change lots ofcode internally, there is a higher risk of regressions, particularly inSQLAlchemy; these regressions are usually worked out within the first fewpoint releases of a new minor release. As always, downstream applications should run theirtest suites and report any issues with a new minor release.

• Behavioral changes - Most behavioral changes are subtle and unlikely to cause issuesin the general case. These changes may however be backwards-incompatible withend-user code that is either relying upon a previously broken behavior, orwhich was working around the old behavior which will no longer produce thesame result. A typical example is a SQL rendering that was previously notquoting or escaping correctly, which is then repaired; downstream applicationswill typically be working around this problem by applying the quoting manually,which becomes redundant once SQLAlchemy repairs it. An example of such a changeisThe column-level COLLATE keyword now quotes the collation name,which adds quoting to database collation names which must be specified ina case sensitive manner.

  Behavioral changes that aren't expected to cause issues are nonethelessdocumented in case some unforeseen issue arises; an example isFOR UPDATEclause is rendered within the joined eager load subquery as well as outside¶,which modifies how "FOR UPDATE" is rendered in a SELECT that includes joinedeager loading. This change impacts users of MySQL the most, as it worksaround a known MySQL issue and will suddenly start locking table rows froma related table in a joined-eager load, whereas this was not the case beforeon this particular backend.

• API Deprecations - SQLAlchemy and related projects attempt to add new deprecationsonly within a minor release and not within a point release. Any deprecatedAPI should to the greatest degree possible emit aDeprecationWarning whenthat API is used. While this was not always the case for older versions, thegoal is that deprecations are only added in minor releases and that theyshould emit warnings when used. This is so that projects have an entireminor release cycle to migrate off the old API and that the deprecation iseasy to recognize.

• Removal of previously deprecated APIs - an API that was deprecated in aparticular minor release may be removed as soon as the next minor release, thoughoften a deprecated API will remain for multiple minor releases. In modernreleases, deprecated APIs should be emitting warning when used throughout thespan of a particular minor release.

Major releases

Major releases refer to the general maturity state of the project, which is amulti-year status. A project begins with 0, e.g. sqlalchemy-collectd-0.0.4,which indicates the range of maturity from initial alpha releases intolong-term stable releases, with the notion that major breaking changes mayoccur across each minor release. At major version 1, the project is consideredto be mature. Major version 2 and higher each indicate major new shifts for theproject of a similar nature as that of Python 2 to Python 3.