Mailing-List: contact dev-help@avalon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Avalon Developers List" <dev@avalon.apache.org>
Message-ID: 
 <03334AAF1DF8D2119B1000A0C9E32F58065EFEDB@us-pb-xmsg-2.am.sony.com>
From: "Farr, Aaron" <Aaron.Farr@am.sony.com>
To: avalon-dev <dev@avalon.apache.org>
Cc: "'Leo Simons'" <lsimons@jicarilla.org>
Subject: Regarding The Avalon Framework
Date: Thu, 8 Jul 2004 13:06:01 -0700 
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"

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: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org