Re: [SpecGL Draft] D4 Define how to handle each deprecated feature

sorry for the delay in responding.  I agree with Dom's comments and have 
provided additionally suggestions.

>Le lun 28/06/2004 à 23:35, Karl Dubost a écrit :
> > D.4 Deprecation

Either Keep the introductory paragraph that is there and modify it with the 
new definition or merge this in somewhere else.

"The need for deprecation comes about when there are features (e.g., 
function argument, element, attribute) defines in the specification that 
have become outdated and is being phased out, usually in favor of a 
specified replacement. It means that the feature is still there and 
functional, but (1) there is a better way of achieving the same thing and 
the WG prefers you use this better way or (2) the feature is not being used 
and the WG wants to clean up the specification and eventually remove the 
feature. From a user point of view, a deprecated feature is one that should 
not be used anymore, since it may be removed from future versions of the 
specification. Deprecated features are no longer recommended for use and 
may become obsolete and no longer defined in future versions of the 
specification. "

> > Proposal:
> > ---------------------------------------------
> > Good Practice:
> >       Define how to handle each deprecated feature
> >
> >
> > Meaning:
> >       A feature is usually defined when there is a better mechanism 
> inside
> > the technology, or another technology that could be used, to achieve
> > the same effect (with often more possibilities).
>
>I don't understand this defintion; could you propose another wording or
>explain with more details what you mean?

I also don't like using 'mechanism'.  Suggest replacing with:
By deprecating a feature, the WG indicates its desire that the feature 
disappear from the specification.  The motivation may be to convert an old 
feature to a newer one or to remove an old, dangerous, redundant or 
undesirable feature.  Regardless of the reason, it is important to define 
the affect this will have on implementations that may encounter this 
feature (e.g., consumer products such as user agents or producer products 
such as ???).  Will use of the deprecated feature be tolerated?  Will it 
signal an error or a warning?

> >  It is important to
> > define the behavior of the different kind of products when they have to
> > read or produce deprecated features.
>
>Either use "classes of products" or "implementations"; I think
>introducing this new wording (kind of products) is going to be
>confusing.
>Maybe using "consume" instead of "read" would better align with the
>other sections as well.
>
> >  The feature is likely to become
> > obsolete in the next version of the technology.
>
>I don't think this is useful to add here.
>
> > Care:
> >       It will help to establish transition/evolution strategies for the
> > users of the technology. It will help a consistent behavior when the
> > technology is implemented in different products and will be
> > particularly helpful when products can deal with different versions of
> > the technology.
>
>Here is a proposed rewording:
>Defining how deprecated features are handled allows to establish a
>smoother transition for the users of the specified technology, and
>ensure more consistency of the behavior across implementations. It is
>also particularly important for implementations that needs to support
>different versions of the specification.

Agree with rewording.  But, better english to say:   s/allows to 
establish/provides a/

> >  For example, should a tool, able to read an old version
> > of the document, propose helping mechanism or conversion to the new
> > method which are preferred.
>
>Here is another proposed rewording:
>For instance, the specification may require that an implementation
>supports both the features of the new and the old specifications, or
>suggest a converting mechanism.

Agree with this rewording.

--regards
Lynne

Received on Friday, 2 July 2004 08:56:35 UTC