forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <>
Subject Compatibility break reporting (Re: cvs commit: xml-forrest status.xml)
Date Sat, 16 Nov 2002 17:54:27 GMT

On Sat, Nov 16, 2002 at 05:31:43PM -0000, wrote:
> jefft       2002/11/16 09:31:43
>   Modified:    .        status.xml
>   Log:
>   Add an attempt at a 'compatibility' issue

To document backwards-compat breaks, how about we adopt a format
something like this:

  <issue id="...." date="2002-xx-xx">
      <!-- Brief overview of what happened -->
      version="..."date="..."> <!-- These both optional -->
      <!-- Inform the user whether they are affected -->
      <!-- Describe what happened (and why) -->
      <!-- Describe how the user can rectify the situation -->

Eg, I just made a change that will break the credits images in lots of
Forrest sites made with 'forrest seed' from CVS prior to 2002-11-05.
For this, the compatibility report could look like:

  <issue id="skin_images" date="2002-11-17">
      Images removed from default Forrest <code>forrest-site</code>
      and <code>avalon-tigris</code> skins
    <affected date="2002-11-05">
      Users of these skins who may use the deleted images in a
      project-specific <code>skinconf.xml</code> file.  Many earlier users of
      Forrest fall into this category, as these images were in the default
      skinconf.xml in pre-0.2 versions of Forrest.
        Removed these files, as they were Forrest-site-specific and not used
        directly in skins:
      <p xml:space="preserve">
      If your project uses <code>skin/images/built-with-cocoon.gif</code>,
      <code>skin/images/centipede-logo-small.gif</code> or any other deleted
      file, please:
          Copy the referenced images into your project's
          <code>src/documentation/resources/images</code> directory, or
          wherever the <code>project.images-dir</code> property points.
          Change the skinconf.xml reference from <code>skin/images</code> to

So the questions are:

 - Do we want to take backwards-compat this seriously this early on?
 - If so, does everyone commit to writing these things up when they
   break something?
 - Is this general format acceptable?  We can refine things as we go..


View raw message