cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geoff Howard <coc...@leverageweb.com>
Subject Re: [proposal] Cleaning up our component library
Date Wed, 28 Jan 2004 15:44:54 GMT
Vadim Gritsenko wrote:

> Carsten Ziegeler wrote:
> 
>> Joerg Heinicke wrote:
>>
>>> So alltogether:
>>>
>>> a) Components that are just renamed or replaced with only sitemap 
>>> changes (FileGenerator => XMLGenerator, DirectoryGenerator => 
>>> TraversableGenerator (or however it is called ;-) ), StreamGenerator 
>>> => XMLGenerator + ModuleSource) are deprecated in 2.1 and removed in 
>>> 2.2.
>>> b) Components that need "real" application changes as 
>>> processPipelineTo or anything similar are also deprecated in 2.1, but 
>>> will be kept in 2.2.
>>> c) Deprecation messages:
>>> Strict deprecation for a) components. 80% are catched by "file" => 
>>> "xml" and "file" is the default generator and "xml" will be it.
>>> Loose deprecation with a warning on every usage (otherwise they are 
>>> to easily lost in the logs) for b) components. If we also use strict 
>>> deprecation here, we don't really need b).
>>
>> Some general notes:
>>
>> I think whatever we do in this area, we should make a vote for each 
>> change.
> 
> Totally agree. Please do not make such changes without voting first on 
> each change.
> 
> For example, I already have objectsion against renaming File / Directory 
> Generators - those are the most intuitive / easy-to-use components we 
> have today. File and Directory abstractions are well known throughout 
> the computing world (including non-English speakers); and File / 
> Directory does not have to be on the file system, they could be 
> anywhere: WebDAV, XML:DB, etc.
> 
> OTOH, TraversableGenerator is just *horrible* name.

I am sort of one the fence here.  I agree with the premise that our 
names are misleading in many cases.  However, I think mass confusion may 
ensue if we rename mainstay components like the FileGenerator.  Of 
course, we can move the real implementation to an XMLGenerator and make 
FileGenerator extend it, deprecating FileGenerator.

I wonder if we should move much more slowly on the removal end, focus on 
better naming conventions moving forward, and provide a very clear 
documentation explaining the paradox (e.g., "File" generator really 
works with  any source which is already unparsed XML at its nature, if 
an appropriate Source exists to get at it).  As people have been free to 
subclass any existing generator, I don't know how we can expect any real 
renaming to be "sitemap only".

Now, I say that mostly with the users list in mind and I defer to your 
(Joerg's) opinion greatly about that.  (for devs unsubscribed on the 
users list, Joerg is absolutely indispensable there, IMO).

>> And we should only move things into the deprecated part if there is a
>> usable alternative. IMHO, using flow instead of a transformer isn't 
>> really
>> an alternative as the overhead is way to much (just my opinion here).
> 
> -1 to replacing of SourceWritingTransformer with the flosw. It's name is 
> a bit misleading, and SourceCopyAction sounds better to me, but any 
> alternative to SWT must be non-flow.

You mean to change SWT to an Action?

>> And we should avoid the renaming trap - which means renaming things just
>> because a "not so perfect" name has been chosen in the first place. IMHO
>> there is no real use in this.
> 
> Ditto.

I sympathize with this too.  The amount of documentation, (cvs, wiki, 
books, other external) that would become outdated scares me here.  The 
naming is confusing, but not as confusing as inaccurate docs.

What about doing "weak" deprecation, with good explanation that the move 
is in name only.  INFO level logging on each use seems reasonable.  But 
I'd propose that since this would come late in the 2.1 cycle that 
removing in 2.2 is too soon.  I'd propose continue deprecation in 2.2 
and remove only after that - maybe even a major version (i.e., 3.0).

Geoff


Mime
View raw message