Backwards-incompatible changes for GeoDjango not documented (e.g., PostGISAdaptor -> PostGISAdapter)

[Brandon Konkle]

The django.contrib.gis.db.backend.postgis.adaptor.PostGISAdaptor class has been renamed to django.contrib.gis.db.backend.postgis.adapter.PostGISAdapter in 1.2, but this is not documented in ​http://docs.djangoproject.com/en/dev/releases/1.2/. I'm attaching a patch that will add a quick note about it.

[Brandon Konkle]

Correction - I forgot the 's' on the end of 'backends' for the renamed class. I'm uploading a new diff.

[Russell Keith-Magee]

If this is a backwards incompatible change, it's not just a documentation issue - we need to look at whether the change is necessary at all. Pushing to the GIS so it get specific eyes from Justin.

[jbronn]

Replying to russellm:

If this is a backwards incompatible change, it's not just a documentation issue - we need to look at whether the change is necessary at all. Pushing to the GIS so it get specific eyes from Justin.

It's a matter of debate to whether this is a backwards-incompatible change -- the root cause of the issue is that SpatialBackend (and SpatialBackend.Adaptor) no longer exists due to multiple-database support, however, it was never documented to begin with.

I did indeed rename the Adaptor objects to the more common spelling of Adapter; providing aliases is a possibility -- however, I also changed the root namespace to django.contrib.gis.db.backends (the s was added), thus even the aliases wouldn't even be truly backwards-compatible.

Now that we're on the subject, I'm reminded of another change that must be documented: django.contrib.gis.models.SpatialRefSys no longer exists (again, due to multi-db support). This, and the GeometryColumns model were moved to each respective backend (e.g., django.contrib.gis.db.backends.postgis.models), and can also be accessed by methods on the connection (connection.ops.spatial_ref_sys, connection.ops.geometry_columns).

I agree that documenting these changes is necessary, however, all of the name changes have been done to internal APIs within GeoDjango. But I disagree with backing out of these changes now (minus possible model alias to default connection in django.contrib.gis.models) in the name of preserving compatibility for those relying on undocumented APIs.

[jbronn]

Provides backwards-compatibility aliases.

[jbronn]

Added aliases to django.contrib.gis.models.

[Alex Gaynor]

Justin, can you add a note to the backwards compatibility timeline doc, so we can (amongst other things) remember when to remove these aliases.

[Russell Keith-Magee]

@jbronn: What's the status on this ticket? Is there a reason you uploaded a patch to the ticket rather than committing?

[jbronn]

(In [13097]) Fixed #13315, #13430 -- Recreated django.contrib.gis.db.backend module with SpatialBackend alias and added Adaptor alias for backwards-compatibility purposes; added GeoDjango 1.2 backwards-incompatibility documentation and release notes; added a section in the docs about how MySQL is a crippled spatial database; updated versions in install docs.

[anonymous]

Justin: do you mind adding a note to internals/deprecation.txt?

[Jacob]

Milestone 1.2 deleted