attrs/docs/backward-compatibility.rst

Backward Compatibility
======================

.. currentmodule:: attr

``attrs`` has a very strong backward compatibility policy that is inspired by the policy of the `Twisted framework <https://twistedmatrix.com/trac/wiki/CompatibilityPolicy>`_.

Put simply, you shouldn't ever be afraid to upgrade ``attrs`` if you're only using its public APIs.
If there will ever be a need to break compatibility, it will be announced in the `changelog` and raise a ``DeprecationWarning`` for a year (if possible) before it's finally really broken.


.. _exemption:

.. warning::

   The structure of the `attr.Attribute` class is exempt from this rule.
   It *will* change in the future, but since it should be considered read-only, that shouldn't matter.

   However if you intend to build extensions on top of ``attrs`` you have to anticipate that.
Clarify backward compatibility + polish API docs 2015-02-01 18:27:36 +00:00			`Backward Compatibility`
			`======================`

			`.. currentmodule:: attr`

Doc typo fixes (#56) Native English speaker fixes 2016-08-15 08:00:23 +00:00			``attrs`` has a very strong backward compatibility policy that is inspired by the policy of the `Twisted framework <https://twistedmatrix.com/trac/wiki/CompatibilityPolicy>`_.
Clarify backward compatibility + polish API docs 2015-02-01 18:27:36 +00:00
Doc typo fixes (#56) Native English speaker fixes 2016-08-15 08:00:23 +00:00			Put simply, you shouldn't ever be afraid to upgrade ``attrs`` if you're only using its public APIs.
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge. 2019-09-09 13:02:16 +00:00			If there will ever be a need to break compatibility, it will be announced in the `changelog` and raise a ``DeprecationWarning`` for a year (if possible) before it's finally really broken.
Clarify backward compatibility + polish API docs 2015-02-01 18:27:36 +00:00

			`.. _exemption:`

			`.. warning::`

Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge. 2019-09-09 13:02:16 +00:00			The structure of the `attr.Attribute` class is exempt from this rule.
Doc typo fixes (#56) Native English speaker fixes 2016-08-15 08:00:23 +00:00			`It will change in the future, but since it should be considered read-only, that shouldn't matter.`
Clarify backward compatibility + polish API docs 2015-02-01 18:27:36 +00:00
			However if you intend to build extensions on top of ``attrs`` you have to anticipate that.