Docs: add a `Semver` section
@@ -177,10 +177,42 @@ information.
geopy does no logging above `DEBUG`.
+Semver
+~~~~~~
+
+geopy attempts to follow semantic versioning, however some breaking changes
+are still being made in minor releases, such as:
+
+- Backwards-incompatible changes of the undocumented API. This shouldn't
+ affect anyone, unless they extend geocoder classes or use undocumented
+ features or monkey-patch anything. If you believe that something is
+ missing in geopy, please consider opening an issue or providing a patch
+ or a PR instead of hacking around geopy.
+
+- Geocoder classes which simply don't work (usually because their service
+ has been discontinued) might get removed. They don't work anyway, so
+ that's hardly a breaking change, right? :)
+
+- Geocoding services sometimes introduce new APIs and deprecate the previous
+ ones. We try to upgrade without breaking the geocoder's API interface,
+ but the :attr:`geopy.location.Location.raw` value might change in a
+ backwards-incompatible way.
+
+- Behavior for invalid input and peculiar edge cases might be altered.
+ For example, :class:`geopy.point.Point` instances did coordinate values
+ normalization, though it's not documented, and it was completely wrong
+ for the latitudes outside the `[-90; 90]` range. So instead of using an
+ incorrectly normalized value for latitude, an :class:`ValueError`
+ exception is now thrown (#294).
+
+
+To make the upgrade less painful, please read the changelog before upgrading.
+
+
Changelog
~~~~~~~~~
-:doc:`Changelog <changelog_1xx>`.
+:doc:`Changelog for 1.x.x series <changelog_1xx>`.
For changes in the 0.9 series, see the
:doc:`0.9x changelog <changelog_09x>`.
