I don't think we should maintain documentation for API changes between UNSTABLE versions, that seems like a recipe for a huge mess to me and lots and lots of duplicate work.

There seems to be two ways you'd upgrade a contrib module:

1. Every time there's an unstable release, upgrade your contrib module
2. wait a while, then upgrade to the latest UNSTABLE (or beta, or 7.0)
Maintaining two sets of upgrade documentation seems to be accounting for
3. Wait a while, then go through UNSTABLE-1, UNSTABLE-2, UNSTABLE-3 one at a time.

3. just looks like a lot of work for no gain to me.

Therefore, if an API changes between UNSTABLE-1 and UNSTABLE-2 - then we should document the 6.x - 7.x upgrade in UNSTABLE-2 as 'this is the most recent unstable release where this particular API was changed'. If UNSTABLE-2 is out, no-one should be trying to upgrade to UNSTABLE-1 at all. If you're upgrading from UNSTABLE-1 to UNSTABLE-2, then the fact that (in this example) permissions changes are there again, means you ought to be able to work out what to do.

In the same way we don't provide database updates for different versions of HEAD, I don't think we should provide API updates for different versions of HEAD either.

Or have I missed something really obvious?

Nat

On Mon, Oct 13, 2008 at 6:02 PM, Gábor Hojtsy <gabor@hojtsy.hu> wrote:
On Mon, Oct 13, 2008 at 7:00 PM, Angela Byron <drupal-devel@webchick.net> wrote:
> Ah, this is how I would handle this:
>
> * Keep the text of the page geared toward people updating 6 to 7 all at
> once. (issue) and (issue); no need to specify when it was added.
>
> * In the table of contents though, under UNSTABLE-2, add the permission
> change with a link to the place that talks about both.

"Place that talks about both" would be the same as in the * before,
right? Somehow we'd still need to point people on what changed in that
section from one UNSTABLE to the other, right? Or did I miss
something?

Gabor