Documenting incompatibilities between releases

[Dianne Richards <di...@gmail.com>]

Because the JPA 2.0 spec is adding a Map<String,Object> getProperties()
method to the EntityManagerFactory interface, I've been forced to change the
Properties getProperties() method on the OpenJPAEntityManagerFactory to
return a Map instead of a Properties object. This creates an incompatibility
with the 1.x.x releases that could break an application that uses this
method. I plan to document this in the Release Notes. Let me know if you
don't agree with this. I also have considered adding a new Appendix to the
manual titled Migration Considerations, and adding this detail. I'd like to
hear opinions on this idea. Also, is there anyplace else where this should
be documented.

-- 
Thanks - Dianne

Re: Documenting incompatibilities between releases

[Donald Woods <dw...@apache.org>]

+1 for adding to Release Notes and to the manual (appendix is fine, as 
long as there is a link to the info in the Intro section.)

What about the 1.2.1 and 1.3.0 releases - should we mention the upcoming 
change and/or mark the method as deprecated?  Should we also think about 
adding the new method to those releases so users can start migrating now?


-Donald


Dianne Richards wrote:
> Because the JPA 2.0 spec is adding a Map<String,Object> getProperties()
> method to the EntityManagerFactory interface, I've been forced to change the
> Properties getProperties() method on the OpenJPAEntityManagerFactory to
> return a Map instead of a Properties object. This creates an incompatibility
> with the 1.x.x releases that could break an application that uses this
> method. I plan to document this in the Release Notes. Let me know if you
> don't agree with this. I also have considered adding a new Appendix to the
> manual titled Migration Considerations, and adding this detail. I'd like to
> hear opinions on this idea. Also, is there anyplace else where this should
> be documented.
> 

Re: Documenting incompatibilities between releases

[Jeremy Bauer <te...@gmail.com>]

Dianne,

I've been asking folks to document issues like these in OPENJPA-773, the
umbrella JPA 2.0 update JIRA.  That way, there is one location for this
information, instead of several.  I haven't proposed that these types of
compatibility issues get documented in release notes yet since the spec is
still in flux and subject to change.  Although, I think it'd be OK to add
the doc updates as long as we are dilligent about keeping them up-to-date
if/when they are impacted by future drafts of the spec.  Making a note in
773 should help serve as a reminder.

Other opinions? Should the release notes and/or manual be updated as these
types of issues are encountered?

-Jeremy

On Mon, Feb 2, 2009 at 3:00 PM, Dianne Richards <di...@gmail.com> wrote:

> Because the JPA 2.0 spec is adding a Map<String,Object> getProperties()
> method to the EntityManagerFactory interface, I've been forced to change
> the
> Properties getProperties() method on the OpenJPAEntityManagerFactory to
> return a Map instead of a Properties object. This creates an
> incompatibility
> with the 1.x.x releases that could break an application that uses this
> method. I plan to document this in the Release Notes. Let me know if you
> don't agree with this. I also have considered adding a new Appendix to the
> manual titled Migration Considerations, and adding this detail. I'd like to
> hear opinions on this idea. Also, is there anyplace else where this should
> be documented.
>
> --
> Thanks - Dianne
>