Firstly, Joda-Time 2.0 is NOT a re-write of Joda-Time. The major version number change signifies that there are some incompatibilities. However, these are as minor as I could make them.
A few methods on Chronology that were deprecated for years have been removed, but most other deprecated and classes methods remain as the benefits of removing them were lower than the damage caused.
The library has moved to JDK 1.5 compatibility, adding generics. Sadly, adding generics to Comparable in some cases caused issues for implementations. The choice was to aim for binary incompatibility at the expense of source incompatibility if the ReadableInstant or ReadableDuration interfaces were implemented directly. If you didn't implement these, or extended the supplied abstract class then you should have no problems. Similarly, ReadablePartial had Comparable added, but if you didn't implement it, or extended the supplied abstract class then again you should have no problems.
In summary, I hope there are no significant binary incompatibilities. If you do find a binary incompatibility that I didn't, I'd like to know, particularly if it affects another open source project. If it is in the next week or so, then perhaps the incompatibilty can be fixed and "jar hell" avoided.
There are a number of semantic changes as well in the corner cases. Again see the release notes.
- Parsing a month-day without a year now selects year 2000 rather than 1970 (so the 29th of February can be parsed)
- Edge cases with a week-based-year and a month are handled better
- Methods that handle daylight savings time (DST) are more consistent, retaining the offset wherever possible during calculations or consistently choosing summer time if not
- Some short time zone IDs have been changed
- DateTimeZone factory taking an ID is now case sensitive
And of course there are some enhancements:
- Static factories now() and parse() added to the main date-time classes
- New classes YearMonth and MonthDay
- API added to plugin to the Joda-Time clock
- Period formatting in multiple langauges
- Parsing of LocalDate/LocalTime/LocalDateTime directly supported (much better than previously)
- Parsing of time-zone IDs and some support for parsing time-zone names (via the builder)
- Better handling of 'Z' when parsing to mean +00:00
- Reliable way to get the start of day for a DateTime - withStartOfDay()
- Convenient way to handle DST, DateTime.withEarlierOffsetAtOverlap() .withLaterOffsetAtOverlap()
- Provide direct conversion from LocalDate and LocalDateTime to java.util.Date
- More constructors and methods for Duration
- More constructors for DateTime
- Support JDK 1.6 pluggable resource providers
- More compatible with the Java Memory Model in JDK 1.5 and higher
- Added support for Joda-Convert without adding a dependency
Hopefully, you can just drop Joda-Time into your application and you will not notice any change. However, you should definitely read the release notes first.
Finally, as I'm sure someone will ask, this doesn't affect ThreeTen/JSR-310. This release was necessary to finally release a lot of bugs and enhancements in Joda-Time.
PS. As a bonus, there is a re-release of the JSP tags library, as apparantly it wasn't in maven central correctly up until now.
PPS. For Hibernate 4.0 support, please use the usertype project.