Backwards-compatibility (Re: Stable stamped version)

[Jeff Turner <je...@apache.org>]

On Tue, Nov 05, 2002 at 04:12:36PM +0000, Ian Blizard wrote:
> Hi all,
> 
> You guys are doing some stunning work, when do you think we'll see the 
> wood for the trees?
> 
> Even an alpha/beta distribution would be very handy, at least then 
> everyone who uses it will have a solid basepoint to start from.

Yes, we're long overdue a release.

That raises the question, what strategy should Forrest take wrt.
backwards-compatibility.

My thoughts:

Forrest is a rapidly evolving, early-lifecycle project.  When the choice
is between improving Forrest, or breaking backwards-compat, I'd go with
improving Forrest.

However, I'd suggest one rule: when backwards-compat is broken, it MUST
be documented as such, and an 'upgrade path' for users supplied.

One of the best examples of change reporting I've seen is Log4j's HISTORY
file.  It lists all user-relevant changes in log4j since October 1999.
Each change is marked by severity:

   [*] Changes that are 100% compatible with existing client code.
  [**] Changes that requiring little or no modification to existing
       client code.
 [***] Changes requiring important modifications to existing client code.


Perhaps we could extend the 'changes' section in status.xml to support
this, where each [***] entry requires a link into a separate 'upgrade
path' page.  If the Forrest site is run as a webapp on cocoondev, we can
then have a 'queryable' changelog: "show me how to upgrade my Forrest
0.3.4 site to Forrest 0.9.0".  This can easily be done with an XPath
expression, and the XPathTransformer in Cocoon's patch queue.


Also, breaks SHOULD also be done just after major version increments.


In order to enforce this backwards-compat policy, I suggest we have a
regression suite of sites which the Forrestbot tries to build once a day.
The Forrestbot can be modified to be able to check out versions of a site
from CVS at certain dates.  I can supply aft.sf.net as a non-trivial
Forrest use-case.  Hopefully, any users seriously relying on Forrest will
either let us use their site for regression testing, or set up a
Forrestbot themselves.

The problem is, there are lots of cases where a small change in Forrest
could possibly break someone's site, but it's highly unlikely.  We need
to tighten and document the contracts between the various parts of
Forrest.


--Jeff

> 
> -Buzz.
> 

Re: Backwards-compatibility (Re: Stable stamped version)

[Nicola Ken Barozzi <ni...@apache.org>]

Jeff Turner wrote:
> On Tue, Nov 05, 2002 at 04:12:36PM +0000, Ian Blizard wrote:
> 
>>Hi all,
>>
>>You guys are doing some stunning work, when do you think we'll see the 
>>wood for the trees?
>>
>>Even an alpha/beta distribution would be very handy, at least then 
>>everyone who uses it will have a solid basepoint to start from.
> 
> 
> Yes, we're long overdue a release.

+1

Do you have any idea on what we need before a 0.3 Alpha release?

> That raises the question, what strategy should Forrest take wrt.
> backwards-compatibility.
> 
> My thoughts:
> 
> Forrest is a rapidly evolving, early-lifecycle project.  When the choice
> is between improving Forrest, or breaking backwards-compat, I'd go with
> improving Forrest.
> 
> However, I'd suggest one rule: when backwards-compat is broken, it MUST
> be documented as such, and an 'upgrade path' for users supplied.
> 
> One of the best examples of change reporting I've seen is Log4j's HISTORY
> file.  It lists all user-relevant changes in log4j since October 1999.
> Each change is marked by severity:
> 
>    [*] Changes that are 100% compatible with existing client code.
>   [**] Changes that requiring little or no modification to existing
>        client code.
>  [***] Changes requiring important modifications to existing client code.
> 
> 
> Perhaps we could extend the 'changes' section in status.xml to support
> this, where each [***] entry requires a link into a separate 'upgrade
> path' page.  

+1000!
I'd put it in the DTD to *require* an attribute that defines how this 
can break backwards compat.

> If the Forrest site is run as a webapp on cocoondev, we can
> then have a 'queryable' changelog: "show me how to upgrade my Forrest
> 0.3.4 site to Forrest 0.9.0".  This can easily be done with an XPath
> expression, and the XPathTransformer in Cocoon's patch queue.

:-?

> Also, breaks SHOULD also be done just after major version increments.

I'd start this rule till we get to a 1.0 version.

> In order to enforce this backwards-compat policy, I suggest we have a
> regression suite of sites which the Forrestbot tries to build once a day.

+1

> The Forrestbot can be modified to be able to check out versions of a site
> from CVS at certain dates.  I can supply aft.sf.net as a non-trivial
> Forrest use-case.  Hopefully, any users seriously relying on Forrest will
> either let us use their site for regression testing, or set up a
> Forrestbot themselves.

You are our Anteater guru, why not set up a suite of Anteater tests?
It would be an excellent start for a suite to use in Cocoon.

> The problem is, there are lots of cases where a small change in Forrest
> could possibly break someone's site, but it's highly unlikely.  We need
> to tighten and document the contracts between the various parts of
> Forrest.

There is only one really important contract ATM, which is the DTD; IMHO 
we should concentrate on those till a 1.0 release.

Then add other things to the tests as the problems arise during the 0.x 
release cycle.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------