Changes between Version 7 and Version 8 of ContribEmailAuth

Timestamp:

Sep 20, 2013, 9:35:31 PM (11 years ago)

Author:

Russell Keith-Magee

Comment:

Added summary of the design decisions

ContribEmailAuth

@@ -9 +9 @@
  * https://groups.google.com/d/msg/django-developers/rb7v9kVAK3I/1yQYQPN-IcsJ
 
-A number of solutions have been proposed. Here is a summary of the most viable candidates:
+== Design ==
+
+The end goal is to provide as a built-in feature of Django a User model that is an exact analog of the historical contrib.auth.User, but with email as the identifying field. 
+
+There are two major design questions that need to be answered:
+
+=== Code Location ===
+
+The first question: where should this code live?
+
+==== Option 1: A new contrib.auth.email_user app ====
+
+What it says on the tin. We add a new contrib app to contain the new code. Users install this app and point at the model/forms it provides.
+
+**Advantages:**
+
+* Good separation of concerns. contrib.auth remains essentially unchanged, except for any refactoring of base classes needed to support the new app. Users who don't want EmailUser don't have to carry any extra load from model parsing, import or caching.
+* Sets a good example for third-party apps wanting to provide their own pluggable apps for Users.
+
+**Disadvantages:**
+
+* Requires 2 settings to use the new model -- ``INSTALLED_APPS`` and ``AUTH_USER_MODEL``. The counterargument to this is that users are used to installing apps to get access to models.
+
+==== Option 2: Include EmailUser in contrib.auth ====
+
+This requires the interpretation of ``Meta: swappable`` as "don't make this model visible unless the this model is referred to". This wasn't the original intended interpretation of ``Meta: swappable``, but the implementation supports this usage. If swappable is used in this way, the model is still loaded, parsed, and put into AppCache, but it isn't synchronized to the database, and any attempt to issue a query or generate a FK to the model will raise an error.
+
+**Advantages:**
+
+* Single point of configuration -- the developer need only set ``AUTH_USER_MODEL``.
+
+**Disadvantages:**
+
+* Overhead. Regardless of whether you want to use EmailUser, it must be loaded, parsed, and put in app cache.
+* Arguably sets a bad example. Rather than the historical "one app, one concern", it encourages developers to put all possible models into a single app, and use ``swappable`` to prevent loading of a models that aren't needed at runtime.
+* Depending on exact implementation, may require logic in views, forms, admin etc to control which code is active, depending on the active User model.
+
+=== Code structure ===
+
+==== Option 1: Simple Subclass ====
+
+Just rewrite the User model, but substitute email for username. Essentially copy/paste User, editing as required.
+
+**Advantages:**
+
+* Easy to do, easy to understand the end product.
+
+**Disadvantages:**
+
+* No facility for reuse.
+* Sets a bad example for other developers by doing copy-paste.
+
+==== Option 2: MOAR abstract base classes! ====
+
+(RKM - I'm being facetious with these titles. Feel free to edit with something more meaningful :-)
+
+== Implementations ==
+
+A number of implementations have been provided, providing various combinations of the above design decisions. Here is a summary of the most viable candidates:
 
 == Option 1: Simple auth.User analog ==