I'd personally like to delay as much as possible the writing of the docs while things are still in motion, so we remain flexible with regards to the API. That said this is definitely a 1.7 release blocker.

The general concept is that things need to be either of basic types (str, int, etc.) or be "importable", with their __name__ attribute telling us how.

This means that functions, and classes (actual type, not instances), work out of the box (as long as they are not trapped in a closure).

Anything else can't be "guessed" and need to supply enough information so they can be reconstructed, to do so, they can expose a deconstruct attribute, which is a function that returns a triple (import_path <string>, args <tuple>, kwargs <dict>).

A few remarks:

One of the most common troublemakers is lamba, luckily it's easy to fix, just use a normal function instead.

My patch for #21275 provides a simple class decorator @deconstructible, which should work to reconstruct most class instances.

Right now, if the serializer encounters something it can't serialize, it just gives up. Ideally the interactive prompt would give a few options to choose from. For instance: 1. Cancel, 2. Set to NULL, 3. Continue with a marked error that needs to be hand edited (like for a merge conflict).

This branch enables the serialization process to continue when it encounters things it can't serialize. It replaces the unserializable object by an instance of SerializationError which is an exception that raises itself in its __init__.

The idea is that the user can edit the faulty migration the same way one fixes a merge with conflicts in a VCS. Since SerializationError raises itself if the migration is run, users would get valuable feedback with the traceback.

I'm planning to add interactive feedback as mentioned in the previous post, but I'd like to discuss the details before having a go at it.