Documentation of backwards incompatible changes

[Luke Plant]

Hi all,

The online docs can easily give the impression that we have perfect
compatibility with Django 1.0 — the 'Django over time' section on [1]
has a link to 'Backwards-incompatible changes' [2], which contains
pre-1.0 changes only, and a notice at the top saying you don't need to
read it if your code is post 1.0. Also, the archive of release notes
[3] incorrectly says that BackwardIncompatibleChanges is the place to
look for those following trunk. It's a bit of a mess actually.

The truth about backwards incompatibilities is slightly more complex,
as the release notes of 1.1 show. But we don't currently have a good
place to point people to. Release notes are a bit awkward, because it
can be confusing trying to work out which you should read. If I'm
upgrading from 1.0 to 1.2, do I need to dig out the notes for 1.1 as
well? What about 1.1 RC1, beta 1, alpha 1? We also need a place for
people following trunk to refer to.

I'm proposing UpgradingNotes [4], which I've just started throwing
together. It has everything you need to know in one place. It has
notes for trunk at the top, and links to all the release notes you
need to read, newest release first.

This way, the contents of the top section of this page will be edited
(mainly by committers, but possibly by other users) while there is any
flux in trunk, and it will become part of the release notes when the
next version is released.

Also, the current FutureBackwardsIncompatibleChanges [5] is really
just duplication of part of the 'Deprecation Timeline' docs [6]. I
think the former should be removed.

Thoughts? If other people think this is the right idea, links from
the official docs to BackwardsIncompatibleChanges just need to be
changed to UpgradingNotes.

Luke

[1] http://docs.djangoproject.com/en/dev/
[2] http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
[3] http://docs.djangoproject.com/en/dev/releases/
[4] http://code.djangoproject.com/wiki/UpgradingNotes
[5]
http://code.djangoproject.com/wiki/FutureBackwardsIncompatibleChanges
[6] http://docs.djangoproject.com/en/dev/internals/deprecation/

--
As Ralph Waldo Emerson once said, "I hate quotations."

Luke Plant || http://lukeplant.me.uk/

[Russell Keith-Magee]

On Sat, Nov 14, 2009 at 8:55 AM, Luke Plant <L.Pla...@cantab.net> wrote:
> Hi all,
>
> The online docs can easily give the impression that we have perfect
> compatibility with Django 1.0 — the 'Django over time' section on [1]
> has a link to 'Backwards-incompatible changes' [2], which contains
> pre-1.0 changes only, and a notice at the top saying you don't need to
> read it if your code is post 1.0.  Also, the archive of release notes
> [3] incorrectly says that BackwardIncompatibleChanges is the place to
> look for those following trunk.  It's a bit of a mess actually.

...

> Thoughts?  If other people think this is the right idea, links from
> the official docs to BackwardsIncompatibleChanges just need to be
> changed to UpgradingNotes.

I agree that the current situation is a bit of a mess, and needs to be
cleaned up.

My only question is the extent to which the wiki needs to be involved.
I'm not a huge fan of wikis, especially for official material. In
particular, I don't like the fact that we need to be constantly
vigilant and gardening the weeds when a spammer decides to post links
to his favourite porn/essay site.

The details you currently have on the UpgradingNotes page are
essentially duplicates of what will eventually be in the 1.2 release
notes. So why not cut out the middle man and just use those release
notes?

We can add a stub set of 1.2-final release notes right now, with a big
header that reads "1.2 currently in development". Whenever someone in
the core adds a new feature, we add a section to the 1.2 release docs.
If that means backwards incompatibilities, then make the appropriate
notes.

The home page would then link to the release notes index page; this
page will need a bit of a cleanup to make the notes of past alpha/beta
releases less prominent, but that page could do with a cleanup anyway
(since it has a reference to the backwards incompatible wiki, too).

This has the added benefit that writing the release notes becomes a
lot easier when the time comes - rather than scouring the history for
interesting features, Jacob and James just have task of editing.

Yours,
Russ Magee %-)

[Alex Gaynor]

> --
>
> You received this message because you are subscribed to the Google Groups "Django developers" group.
> To post to this group, send email to django-d...@googlegroups.com.
> To unsubscribe from this group, send email to django-develop...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/django-developers?hl=.
>
>
>

I'm a big +1 on starting the release notes now. Most other projects I
know of start them right after they branch for the release. This also
saves James from pestering us in IRC on the night of releases asking
what's new :)

Alex

--
"I disapprove of what you say, but I will defend to the death your
right to say it." -- Voltaire
"The people's good is the highest law." -- Cicero
"Code can always be simpler than you think, but never as simple as you
want" -- Me

[Luke Plant]

On Saturday 14 November 2009 04:15:26 Russell Keith-Magee wrote:

> We can add a stub set of 1.2-final release notes right now, with a
> big header that reads "1.2 currently in development". Whenever
> someone in the core adds a new feature, we add a section to the
> 1.2 release docs. If that means backwards incompatibilities, then
> make the appropriate notes.
>
> The home page would then link to the release notes index page; this
> page will need a bit of a cleanup to make the notes of past
> alpha/beta releases less prominent, but that page could do with a
> cleanup anyway (since it has a reference to the backwards
> incompatible wiki, too).

That's fine with me, if we can reformat the releases index in a
helpful way. My motivation was to have a single place that
definitively lists all changes that people upgrading need to know
about. For projects in maintenance mode, developers won't care about
new features, and I don't think they should have to expend mental
effort picking through a list of releases to work out which ones are
relevant, or checking all of them just in case, or worrying that they
missed some.

Perhaps we could have two sections on that page — all release notes,
and upgrading notes. Or, next to 'final' releases there could be an
additional link to the 'backwards incompatible changes' section, along
with some notes at the top explaining the page.

Luke