Clarify backward compatibility + polish API docs

CONTRIBUTING.rst

@@ -11,8 +11,7 @@ Here are a few guidelines to get you started:
   Every contribution is valuable and shall be credited.
 - If your change is noteworthy, add an entry to the changelog_.
 - No contribution is too small; please submit as many fixes for typos and grammar bloopers as you can!
-- Don’t *ever* break backward compatibility.
-  If it ever *has* to happen for higher reasons, ``attrs`` will follow the proven procedures_ of the Twisted project.
+- Don’t break `backward compatibility`_.
 - *Always* add tests and docs for your code.
   This is a hard rule; patches with missing tests or documentation won’t be merged.
   If a feature is not tested or documented, it doesn’t exist.
@@ -29,10 +28,10 @@ Thank you for considering to contribute to ``attrs``!
 If you have any question or concerns, feel free to reach out to me.
 
 
-.. _`PEP 8`: http://legacy.python.org/dev/peps/pep-0008/
-.. _`PEP 257`: http://legacy.python.org/dev/peps/pep-0257/
+.. _`PEP 8`: https://legacy.python.org/dev/peps/pep-0008/
+.. _`PEP 257`: https://legacy.python.org/dev/peps/pep-0257/
 .. _`good commit messages`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 .. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/
 .. _changelog: https://github.com/hynek/attrs/blob/master/docs/changelog.rst
 .. _AUTHORS.rst: https://github.com/hynek/attrs/blob/master/AUTHORS.rst
-.. _procedures: http://twistedmatrix.com/trac/wiki/CompatibilityPolicy
+.. _`backward compatibility`: https://attrs.readthedocs.org/en/latest/backward-compatibility.html

attr/_make.py

@@ -43,10 +43,14 @@ def attr(default=NOTHING, validator=None, no_repr=False, no_cmp=False,
 
     .. warning::
 
-        Does nothing unless the class is also decorated with :func:`attr.s`!
+        Does *not* do anything unless the class is also decorated with
+        :func:`attr.s`!
 
     :param default: Value that is used if an ``attrs``-generated
-        ``__init__`` is used and no value is passed while instantiating.
+        ``__init__`` is used and no value is passed while instantiating.  If
+        the value an instance of :class:`Factory`, it callable will be use to
+        construct a new value (useful for mutable datatypes like lists or
+        dicts).
     :type default: Any value.
 
     :param validator: :func:`callable` that is called by ``attrs``-generated
@@ -361,8 +365,8 @@ class Attribute(object):
     *Read-only* representation of an attribute.
 
     :attribute name: The name of the attribute.
-    :attribute default: see :func:`attr.ib`
-    :attribute validator: see :func:`attr.ib`
+
+    Plus *all* arguments of :func:`attr.ib`.
     """
     _attributes = [
         "name", "default", "validator", "no_repr", "no_cmp", "no_hash",

docs/backward-compatibility.rst

@@ -0,0 +1,19 @@
+Backward Compatibility
+======================
+
+.. currentmodule:: attr
+
+``attrs`` has a very strong backward compatibility policy that is inspired by the one of the `Twisted framework <https://twistedmatrix.com/trac/wiki/CompatibilityPolicy>`_.
+
+Put simply, you shouldn't ever be afraid to upgrade ``attrs`` if you're using its public APIs.
+If there will ever be need to break compatibility, it will be announced in the :doc:`changelog`, raise deprecation warning for a year before it's finally really broken.
+
+
+.. _exemption:
+
+.. warning::
+
+   The structure of the :class:`attr.Attribute` class is exempted from this rule.
+   It *will* change in the future 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.

docs/index.rst

@@ -25,6 +25,7 @@ Project Information
 .. toctree::
    :maxdepth: 1
 
+   backward-compatibility
    license
    contributing
    changelog