On 21 Dec 2009, at 20:06, Luke Plant wrote: >> I've documented it in some detail in the release notes. Is this >> painstaking enough? > > Unless I'm missing something, it's not nearly there (but some of this > may be the 'formal stuff' that Jacob doesn't mind being missing for > now). > > First, views.Feed.get_object() takes different arguments to > feeds.Feed.get_object(). This is pretty confusing, and really needs > to be *much* clearer in the documentation (not just the release > notes). The same goes for the get_feed() method.
You're right. I've now given it a little versionchanged directive in the main documentation, but perhaps this needs to be clearer. Note that get_feed() isn't documented at all, but all the same, I've made it clear it has changed in the release notes. > > The release notes imply that I can just switch from subclassing > feeds.Feed to view.Feed and change get_object(), and it will all work. > I can't see how that is possible: > > - I might have code that calls the constructor of feeds.Feed (or a > subclass) directly. But views.Feed has a different signature > altogether, and feeds.Feed.__init__() does a bit of work that my own > code is going to have to do once feeds.Feed disappears. Obviously > that code is doing something that will have to be done differently > with views.Feed. But how exactly? > > - I might have code that calls the get_feed() method of feeds.Feed > (or a subclass) directly. That method does extra work compared to > views.Feed.get_feed(). When feeds.Feed goes away, what does my code > need to be changed to? > > What I'm looking for is *step by step* instructions on how to update > my code, and a list of *all* the differences between views.Feed and > feeds.Feed, since the former is supposed to be the replacement for the > latter. I shouldn't have to look at *any* of the code or previous > documentation to work out what has changed. *All* the hard work > should have been done for me. This is about maintenance programmers, > who have been given a promise of backwards compatibility, who just > want their application to carry on working. I understand. I've added additional details in the release notes, but do we need step by step instructions on how to upgrade undocumented APIs? As far as the documented API is concerned, very little has changed. Under the hood though, Feed classes have changed significantly. It would require reams of documentation to take into account all the different ways people might be hacking with Feed classes. > > I'm insisting on this, because until we see it, it's very difficult to > work out how "backwards compatible" this really is, and whether we > should deprecate feeds.Feed at all. Jacob was happy for this to go in > without the formal stuff of documenting all this, so I guess we can > punt the decision about whether to deprecate feeds.Feed or not, but we > do need those docs at some point so we can see the implications of > deprecating feeds.Feed. I've gone through my changes and documented exactly what has changed as far as the user is concerned. The old API should be completely backwards compatible; the new Feed view certainly isn't. > > So for now, maybe just update the release notes so they don't say that > the new LatestEntries class is identical to before, or a caveat like > "if you are only using the high level feed framework (the feed() > view)" or something. > I've gone a little further than that in the patch I've just put on the ticket (1), but this probably needs documenting in more detail. Thanks, Ben (1) http://code.djangoproject.com/attachment/ticket/12403/syndication-views-4.diff (Why aren't my diffs showing? Are they too large for trac?) -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
