diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/build/batch.rst | 2 | ||||
-rw-r--r-- | docs/build/front.rst | 28 | ||||
-rw-r--r-- | docs/build/unreleased/1243.rst | 21 |
3 files changed, 50 insertions, 1 deletions
diff --git a/docs/build/batch.rst b/docs/build/batch.rst index 6c2e9d4..b1a1022 100644 --- a/docs/build/batch.rst +++ b/docs/build/batch.rst @@ -230,7 +230,7 @@ constraint named ``ck1``. In order to drop this column, we have to drop the check constraint also:: with self.op.batch_alter_table("some_table") as batch_op: - batch_op.drop_constraint("ck1", "check") + batch_op.drop_constraint("ck1", type_="check") batch_op.drop_column('q') .. versionchanged:: 1.7 Named CHECK constraints participate in batch mode diff --git a/docs/build/front.rst b/docs/build/front.rst index f4eb660..5ca73e5 100644 --- a/docs/build/front.rst +++ b/docs/build/front.rst @@ -89,6 +89,34 @@ Alembic supports Python versions **3.7 and above** .. versionchanged:: 1.7 Alembic now supports Python 3.6 and newer; support for Python 2.7 has been dropped. +.. _versioning_scheme: + +Versioning Scheme +----------------- + +Alembic's versioning scheme is based on that of +`SQLAlchemy's versioning scheme <https://www.sqlalchemy.org/download.html#versions>`_. +In particular, it should be noted that while Alembic uses a three-number +versioning scheme, it **does not use SemVer**. In SQLAlchemy and Alembic's +scheme, **the middle digit is considered to be a "Significant Minor Release", +which may include removal of previously deprecated APIs with some risk of +non-backwards compatibility in a very small number of cases**. + +This means that version "1.8.0", "1.9.0", "1.10.0", "1.11.0", etc. are +**Significant Minor Releases**, which will include new API features and may +remove or modify existing ones. + +Therefore, when `pinning <https://pip.pypa.io/en/stable/topics/repeatable-installs/>`_ +Alembic releases, pin to the "major" and "minor" digits to avoid API changes. + +A true "Major" release such as a change to "2.0" would include complete +redesigns/re-architectures of foundational features; currently no such series +of changes are planned, although changes such as replacing the entire +"autogenerate" scheme with a new approach would qualify for that level of +change. + + + Community ========= diff --git a/docs/build/unreleased/1243.rst b/docs/build/unreleased/1243.rst new file mode 100644 index 0000000..26c8e35 --- /dev/null +++ b/docs/build/unreleased/1243.rst @@ -0,0 +1,21 @@ +.. change:: + :tags: bug, autogenerate, regression + :tickets: 1243 1245 + + As Alembic 1.11.0 is considered a major release (Alembic does not use + semver, nor does its parent project SQLAlchemy; this has been + :ref:`clarified <versioning_scheme>` in the documentation), change + :ticket:`1130` modified calling signatures for most operations to consider + all optional keyword parameters to be keyword-only arguments, to match what + was always documented and generated by autogenerate. However, two of these + changes were identified as possibly problematic without a more formal + deprecation warning being emitted which were the ``table_name`` parameter + to :meth:`.Operations.drop_index`, which was generated positionally by + autogenerate prior to version 0.6.3 released in 2014, and ``type_`` in + :meth:`.Operations.drop_constraint` and + :meth:`.BatchOperations.drop_constraint`, which was documented positionally + in one example in the batch documentation. These two signatures have been + restored to allow those particular parameters to be passed positionally. A + future change will include formal deprecation paths (with warnings) for + these arguments where they will again become keyword-only in a future + "Significant Minor" release. |