Nobody reads the BackwardsIncompatibleChanges page

[daonb <bennydaon@…>]

From the django irc room:

out))
[10:49am] daonb: I'm trying to test the trunk and here's what I'm getting - http://dpaste.com/70874/ - 
I'm using 2.5.1 and postgres_psycopg2 on a OSX 10.5
[10:54am] Matro: huh, was get_<field>_filename removed?
[10:55am] mattmcc: Nobody reads the BackwardsIncompatibleChanges page.
[10:56am] Matro: I kept finding the one from the last revision
[10:56am] Matro:
[10:56am] mattmcc: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges#Filestoragerefactoring
[10:58am] daonb: I'll read it, but I just did an 'svn up' and 'python setup.py install' and tested my installation. 
using runtests.pt. It should pass out of the box
[10:58am] 

[Russell Keith-Magee]

What's your point? This isn't a bug report, it's a casual observation of common human behavior.

[daonb <bennydaon@…>]

Add a link to the compatibility wiki page

[daonb <bennydaon@…>]

I behaved like that because I didn't know where to look for documentation. Some people don't read it because they don't know about it. 1.0 can help by pointing us ignorant 0.96 users to the right doc.
(I meant to added my patch when I opened the ticket but I mistakenly pressed submit without attaching this small documentation fix, sorry.)

[Julian Bez]

No one reads the README. But it is true that the BackwardsIncompatibleChanges might be difficult to find for new users. Is it linked from the docs etc.?

[Benny Daon]

There are a few links in the docs, but no definitive guide:

$ grep -i -l incompatib docs/*.txt
docs/index.txt
docs/install.txt
docs/release_notes_0.96.txt
docs/release_notes_1.0_alpha.txt
docs/release_notes_1.0_alpha_2.txt

I'm an 0.96.2 developer and am struggling with 1.0 (my runtests.py still fails). IMHO we should improve the docs by focusing on helping 0.9X users migrate to 1.0. If you're interested, I can turn the wiki page into a doc where errors like the one below are mapped to compatibility issues :

  File "/Library/Python/2.5/site-packages/django/db/models/fields/__init__.py", line 430, in Field
    def formfield(self, form_class=forms.CharField, **kwargs):
AttributeError: 'module' object has no attribute 'CharField'

As for the README, If only one person reads it, we should delete it.

[Malcolm Tredinnick]

Please don't reopen tickets that have been marked as wontfix. We will prepare a porting guide as we get a bit closer to 1.0. There are just higher priorities right now. You should feel free to start a wiki page to do just that to get the ball rolling if you like. Don't change the BackwardsIncompatibleChanges page, since that's already serving a specific purpose. But by all means start a new page.

It wouldn't be appropriate add a link to the README, since that file is for the release, not a pointer to highly active in-development, always-changing code. It serves a different purpose than for people using an absolutely latest checkout. So I'm going to reclose as wontfix, since the premise of the ticket is inaccurate and the actual problem you seem to be having (forwards porting from 0.96 to 1.0) is something we'll try to help people solve more directly for 1.0.

[Gary Wilson]

Malcolm beat me to it, but yes, we are interested in a porting guide for 0.96 users upgrading to 1.0. You could use the BackwardsIncompatibleChanges page as a start; however, we would like something polished with the intention of being included in the official documentation for the 1.0 release. This means that it should be a ReST document that organizes the changes into logical sections, with emphasis on the higher-impact changes.

But please, open a new ticket for this.