Hi,
This involves removing 2 of the 4 APIs. Indeed, 2 APIs take an olddoc parameter of a XWikiDocument type. The only reason for this is because the notification mechanism requires two documents so that it can check if the new one has differences over the old one and send notifications accordingly. However this need should be an implementation need and should not surface in the API. Hence XWIKI-1517. BTW this change allows fixing http://jira.xwiki.org/jira/browse/XWIKI-1518 and some other potential bugs too.
Note: I'm not changing the *.api.XWiki object (only the one in *.xwiki.XWiki).
This change will a small impact on people building XWiki applications on top of the XWiki platform but not on end users. I feel this is still ok because:
* We need to improve our API if we want to progress in improving XWiki
* The alternative is to create a XWiki 2.0 version but we won't have enough manpower to 1) continue supporting the 1.x line and 2) to build XWiki 2.0 from scratch. I think our only reasonable option is to build on XWiki 1.x and start refactoring the internal APIs slowly, a bit in each version.
* I'll document this in the release notes
* It's easy to fix for anyone hit by this
* End users are not touched
* It fixes current existing bugs
* It makes the API easier to use. Right now in 99% of the code I had to change the olddoc was simply a clone of the current doc thus making the call useless
So here's my +1
Thanks
-Vincent