Rebecca wrote up compatibility requirements to support upgrade.
You can find them at:
http://wiki.glassfish.java.net/Wiki.jsp?page=UpgradeCompatibilityRequirements
I've also included them below.
Let us know if you have any concerns.
-----
Upgrade Compatibility Requirements
This is a set of guidelines for keeping the application server releases
backward compatible and upgradable as we move forward with V3. All app
server components should review their design changes in relation to
these guidelines.
Backward compatible in this case means the ability to run unaltered the
domains of a previous product release with the new appserver bits. For
example, AS10 bits should be able to run AS9.1x domains unaltered.
Likewise GlassFish V3 should be able to run GlassFish V2.x domains
unaltered.
Common changes that break version backward compatibility.
* Changing the signature of methods in the public API. This can
cause an exception to be thrown on method access.
Any public API changes must be presented to and accepted by the CCC.
* Changing the structure of key configuration files. (e.g.
domain.xml), causing parsing errors or adding new required values
to config files could cause problems.
Anything new must be treated as optional and not required.
* Changing the meaning of configuration file data in a significant
way. (For example, the text value of element 'a' represented the
number of allowed connections. Now it means number of times to
retry a connection.)
Old and new interpretations must be supported.
* Moving the location of a predefined file and not adding a rule to
the new code to look in the old location.
Both the old and new locations must be supported.
* Changing of default database usually means some revision is
needed to the domain.xml data.
Be mindful to minimize the impact of this type of change.
* Changes to auto-generated code (e.g., the APIs in JSP code generation).
Generated code must be backward compatible or it must be
detectable and regenerated.
The general tests for verifying appserver code is backward compatible are:
* Can the new appserver bits point to the old domain and run
everything in it without error or changes?
* Can the old domain be copied to a new location and the new
appserver bits run it without error or changes?
* Can the new appserver bits configure and deploy a new app to the
old domain and run it successfully? It is only required that the
altered domain run with the new appserver bits.