Avaloners, There has been some controversy about the status of framework documentation under the new site. I'm hoping to clarify everything in this email without starting any flame-wars.
Several individuals including myself have expressed some concerns that can be summarized as follows: The Avalon Framework documentation has been removed and what is left is (buried) under the component specification section. Moreover, the documentation refers to Merlin-specific features of the Avalon framework such as constructor dependency injection [1]. This can cause confusion for users of other Avalon-based containers and platforms. With that out of the way, let's look at what we can do to rectify the situation. Avalon's Stewardship ==================== Avalon has developed over the years to provide a complete platform for container development. That includes many things above and beyond the simple Avalon framework which has always been the core of this project. At the same time Avalon has aimed to provide not only a complete platform but a _common_ platform for others to use in developing similar container technologies. Avalon has been entrusted with the stewardship of that core framework which as imperfect as it is is widely used in and out of Avalon and Apache. For this very reason changes to the framework API have involved a careful and often laborious process. It is inevitable that the framework will evolve to support new features and enhancements such as new forms of dependency injection. Consequently, it will be the responsibility of developers who have written Avalon-based projects to "keep up" if they so desire. However, we need to ensure that such evolution occurs in a responsible manner by using strict versioning controls and providing historic and clear documentation. The Nice Thing About Standards ============================== "The nice thing about standards is that there are so many of them to choose from." --Andrew S. Tanenbaum We need to discover a way to balance support for older Avalon flavors while still allowing the Avalon framework the ability to grow and change. Thankfully, that's not too hard. Here is my suggestion which is open for discussion: 1. Create a section in the site dedicated to the pure and simple Avalon framework This section may be under "Systems" [2] or might be a product right beside Merlin Runtime (I'm favoring product more myself). 2. This framework section will document a series of Avalon framework specifications for each version of the Avalon 4 series. This includes API docs, examples, and discussion of various "optional" contracts which have been included in some containers. 3. The latest framework specification documents will be noted as the current and official specification. Merlin will be the reference implementation of this specification. If this includes major changes which are not backwards compatible then we need to look at bumping the version number up to 5. Okay, so the details are a little muddy. I hope you get the spirit of the idea -- provide documentation for the various incarnations of Avalon framework, be observant of backwards compatibility issues, and provide a clear notice about the current specification. Think of something like the w3c.org's handling of HTML [3] -- there are several versions of the specification and if you still want it you can find the HTML 4.0, 3.2, and 2.0 specifications. Walking the Walk ================ We've discussed the needs for better specifications, TCK, and so on before. This is just one step. I believe it is very important during this process to not only provide a clear standard for the future but also document our past. If nothing else, it is the right thing to do for the many users who have placed trust in us. I'm offering to do most of this documentation. Of course, I have a number of other responsibilities, so if it's just up to me it may take a little while. If you want to help, please do so. If you don't want to help, that's fine, but I ask one thing: please don't block the way. I am not trying to halt further development of the framework or limit Merlin's potential. In fact, I believe this will help development of Avalon-compliant systems by providing the needed documentation. It will also clear up confusion about what it means to be Avalon compliant. If you disagree with the way others have used the Avalon framework, that's fine. Don't use it that way. But please allow us who have invested time and effort in maintaining Avalon to provide documentation to our users. We are asking for nothing more than to be allowed to volunteer our time and have such contributions accepted and recognized. Documentation of current and prior releases of the Avalon framework belongs here at Avalon. I am willing to restore and provide it. I hope others will be too. Thanks J. Aaron Farr SONY ELECTRONICS STP SYSTEMS (724) 696-7653 [1] http://avalon.apache.org/products/runtime/reference/component/ lifecycle/incarnation.html [2] http://avalon.apache.org/products/runtime/system/index.html [3] http://www.w3.org/MarkUp/#previous --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
