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.
Hey, of course! I never had in mind to "just change it".
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.
Ok, I can go with you with the DirectoryGenerator. The only problem here is that it is bound to the file system at the moment. We have the TraversableGenerator in our CVS, which is the more generic implementation, but with a bad name. We had already discussions on its name like HierarchyGenerator. I could also imagine to just replace the DirectoryGenerator with the TraversableGenerator and name the TG as DG.
But it's another point with the FileGenerator. While the abstraction of file might be ok, you just can not read text or html files, but only XML.
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.
That's a good compromise IMO.
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".
Subclassing is a good point. I only wonder if there is so much subclassed.
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).
Thanks.
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.
Ok, I see. Flow is not an option, but a component like the propagated 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.
But if the name is just wrong there is a real use. Also the renaming from File to XML would make it much more consistent as we have a HTMLGenerator, TextGenerator, MidiGenerator, JSPGenerator and so on. They all are files, but could not be read by FileGenerator. The core point of this generator is XML, not file.
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).
I understand your concerns about confusing users. But at the moment I see much more confusion for new users. Users that already know Cocoon and have to change their application because of my proposed changes know what they are doing, it's just a question of informing them appropriately. But new users don't see the concepts as they are no longer clear. The main concept is Separation of Concerns (something like a definitive argument :) ) and if we document this separation it will be much easier to dive into Cocoon. But the components must reflect this separation. If a transformer writes something to DOM or disc then it's just wrong. This is the task of the controller.
The other point is time. I understand that 2.2 is a way to fast for removing/replacing components. But how long will you go with old/wrong/irritatingly named stuff just for compatibility reasons? I like Geoff's proposal of doing the final step (removing) with the next major version 3.0. Before we will have weak (2.1 and 2.2) and strict (2.3, ...) deprecation. This is only the general way to go and we will vote about it for every component individually.
Does this address all of your concerns? WDYT?
Joerg
