forrest-dev mailing list archives

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

On Sat, Nov 16, 2002 at 05:31:43PM -0000, jefft@apache.org 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:


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


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:


<compatibility-breaks>
  <issue id="skin_images" date="2002-11-17">
    <synopsis>
      Images removed from default Forrest <code>forrest-site</code>
      and <code>avalon-tigris</code> skins
    </synopsis>
    <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.
    </affected>
    <description>
      <p>
        Removed these files, as they were Forrest-site-specific and not used
        directly in skins:
      </p>
      <p xml:space="preserve">
        src/resources/skins/avalon-tigris/images/ant_logo_small.gif
        src/resources/skins/avalon-tigris/images/built-with-cocoon.gif
        src/resources/skins/avalon-tigris/images/centipede-logo-small.gif
        src/resources/skins/basic/images/ant_logo_medium.gif
        src/resources/skins/basic/images/built-with-cocoon.gif
        src/resources/skins/basic/images/krysalis-compatible.jpg
        src/resources/skins/forrest-site/images/built-with-cocoon.gif
        src/resources/skins/forrest-site/images/centipede-logo-small.gif
      </p>
    </description>
    <fix>
      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:
      <ul>
        <li>
          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.
        </li>
        <li>
          Change the skinconf.xml reference from <code>skin/images</code> to
          <code>images</code>.
        </li>
      </ul>
    </fix>
  </issue>
</compatibility-breaks>


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..



--Jeff

Mime
View raw message