[xwiki-devs] [Discussion] Merge Annotations with Comments
Hi devs, Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes. A summary of the changes contained by the pull request are described in the jira issue [2]. The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations. An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle. WDYT? Thanks, Eduard ---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540
On Thu, Feb 16, 2012 at 7:37 PM, Eduard Moraru <enygma2002@gmail.com> wrote:
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes.
A summary of the changes contained by the pull request are described in the jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
I suppose there is also the option to store comments as annotations (targeting the entire document), but then you have to migrate comments. I think I prefer making commentsinline.vm an aggregator, i.e. the second option. Thanks, Marius
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Approach to aggregate both types is possible. However this will require some changes in existing APIs. There is the doc.getComments() API which could be extended with a parameter saying wether we want to add the annotations or not. The default behavior could be a setting in the xwiki.cfg. This might also require to update the REST api. Ludovic 2012/2/16 Eduard Moraru <enygma2002@gmail.com>
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes.
A summary of the changes contained by the pull request are described in the jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost
Hi Edy, great initiative! On Fri, Feb 17, 2012 at 9:31 AM, Ludovic Dubost <ludovic@xwiki.com> wrote:
Approach to aggregate both types is possible. However this will require some changes in existing APIs. There is the doc.getComments() API which could be extended with a parameter saying wether we want to add the annotations or not.
The default behavior could be a setting in the xwiki.cfg.
This might also require to update the REST api.
Ludovic
2012/2/16 Eduard Moraru <enygma2002@gmail.com>
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes.
A summary of the changes contained by the pull request are described in the jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
I like this approach better since it doesn't break existing APIs, keeps all the existing functionality of both annotations and comments and doesn't require a migrator. One question I have with this scenario however is this: would one be able to respond to an annotation with threaded comments? In any case, we could have a first version where annotations are shown as top-level comments that cannot accept sub-comments, which would already be a good start. Guillaume
WDYT?
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
That could indeed be a limitation which is no so good. One of the objective of merging is to be able to have discussions on an annotation. We have to have this. Ludovic 2012/2/17 Guillaume Lerouge <guillaume@xwiki.com>
Hi Edy,
great initiative!
On Fri, Feb 17, 2012 at 9:31 AM, Ludovic Dubost <ludovic@xwiki.com> wrote:
Approach to aggregate both types is possible. However this will require some changes in existing APIs. There is the doc.getComments() API which could be extended with a parameter saying wether we want to add the annotations or not.
The default behavior could be a setting in the xwiki.cfg.
This might also require to update the REST api.
Ludovic
2012/2/16 Eduard Moraru <enygma2002@gmail.com>
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes.
A summary of the changes contained by the pull request are described in the jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
I like this approach better since it doesn't break existing APIs, keeps all the existing functionality of both annotations and comments and doesn't require a migrator.
One question I have with this scenario however is this: would one be able to respond to an annotation with threaded comments? In any case, we could have a first version where annotations are shown as top-level comments that cannot accept sub-comments, which would already be a good start.
Guillaume
WDYT?
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost
Le 16 févr. 2012 18:38, "Eduard Moraru" <enygma2002@gmail.com> a écrit :
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes.
A summary of the changes contained by the pull request are described in
the
jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
I'm tending to prefer a proper migration. I've played in the past with aggregation of both classes on a small "recent reviews" macro, and I recall some (non-trivial) HQL queries were a pain to write, when doable in a single query at all. I can look for specific examples if needed. I fear that if we let both classes live together, some potential future UI or service or whatever that exposes boths in a unified manner might be harder to implement. Jérôme
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
The problems that I am facing now are related to 2 things: = Approach 1 = If you use only XWiki.XWikiComments (extended with annotation fileds as the pull request is now), you lose the Annotation feature's capability to specify a different AnnotationClass. This means that, if you want to customize the annotation, you need to extend the XWikiComments class directly, and nothing else. This might break existing clients that have provided their own annotation class and will not display their annotations. Writing a migrator for that would imply looking at the configured annotation class that they have provided, update XWikiComments class with the new fields that might be present in that annotation class and convert the annotation objects to use the updated XWikiComments class instead. Would that be enough? This solution will ensure that both "annotation" and "comment" IDs are in the same namespace and are unique. This also ensures that: - the replyTo field points to a proper object ID of class XWikiComments - the html IDs are unique in the page so that the permalinks and anchors for jumping to the annotation and back to the comments tab work - the comments are naturally sorted by ID General downside of solution 1: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page. = Approach 2 = The merging solution has a few problems of it's own: a) The annotation service returns java object Annotations, while the commentsinline.vm works with XWiki API objects. To avoid this problem, we can just do what the old AnnotationsTab did, and that is to directly get the XWiki objects stored in the page using the class configured in the annotations config. Downside: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page. b) Merging things means that we keep both the comments and annotations as separate entities. This means that each have their own ID namespace, causing collisions for the replyTo and permalink features. To avoid this, we would have to do some not-so-nice tricks and mark annotations ID (like "annotation1") so that they are separated from regular comments IDs (when used in the replyTo field). b.1) One solution would be to change the replyTo field's type from Number to String so that we can store this separation. Downside1: This still requires a migration. Downside2: because this means to use the solution for a), we still loose the ability to change the annotation backend. b.2)The other solution would be to use the annotation service API when getting the list of annotations and make a convention when an annotation is created so that it's numeric ID starts from a very large number (like 1.000.000 or more). Downside: Same as problem a): we have to work with 2 types and lots of "IF statements" when processing the comments. Ex: One type has comment.number (for comments), while the other one has comment.id (for annotations). Same thing for dates: comment.getProperty('date').value vs comment.date. General downside of solution2: Since they are merged and no longer naturally sorted by object ID, the comments and annotations also need to be sorted by date. = Conclusion= As I look more into the problem, it does seem that the first approach is the best, having the least number of compromises and doing a better job at semantically merging the two concepts into one. Do you agree? Thanks for your feedback, Eduard On Fri, Feb 17, 2012 at 11:43 AM, Jerome Velociter <jerome@winesquare.net>wrote:
Le 16 févr. 2012 18:38, "Eduard Moraru" <enygma2002@gmail.com> a écrit :
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their
work
with minor changes.
A summary of the changes contained by the pull request are described in the jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
I'm tending to prefer a proper migration. I've played in the past with aggregation of both classes on a small "recent reviews" macro, and I recall some (non-trivial) HQL queries were a pain to write, when doable in a single query at all. I can look for specific examples if needed. I fear that if we let both classes live together, some potential future UI or service or whatever that exposes boths in a unified manner might be harder to implement.
Jérôme
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Actually I was replying to Guillaume and I was thinking about the same set of issues that you mentioned for 2/. In short, it feels to me that the merging with comments is a particularization of the annotation system, which we could make by default in XE, but still allow people that want to change it to change it, with a bit of code / knowledge about what they're doing. I think very little people used annotations let alone customized the annotations class, in the default XE, so, using the 80/20 rule, we can do it. On 02/17/2012 12:31 PM, Eduard Moraru wrote:
The problems that I am facing now are related to 2 things:
= Approach 1 =
If you use only XWiki.XWikiComments (extended with annotation fileds as the pull request is now), you lose the Annotation feature's capability to specify a different AnnotationClass. This means that, if you want to customize the annotation, you need to extend the XWikiComments class directly, and nothing else.
Why would you? I mean, the way I see it, this should be just a change in the annotations config (from annotationsclass to xwikicomments class) with a bit of hairstyling for the XWikiComments class to contain the things needed for annotations (note that we already have an unused field in XWikiComments designed for that -- highlighttext or something). What customizers should lose only (in my view) is the possibility to see annotations in the comments tab, that's it. We can even leave the annotations tab (who made it use AnnotationClass objects? because if I remember correctly, when I wrote it, it was using the annotations service to get annotations, regardless of where / how they're stored), and we hide it by default. So displaying it for customizers should only be a matter of setting in the preferences.
This might break existing clients that have provided their own annotation class and will not display their annotations.
As per my comment above, they will just have to enable the annotations tab. Or not even, since annotations tab is enabled by default in the current version, if they don't update their preferences, annotations tab will still stay visible.
Writing a migrator for that would imply looking at the configured annotation class that they have provided, update XWikiComments class with the new fields that might be present in that annotation class and convert the annotation objects to use the updated XWikiComments class instead. Would that be enough?
I think we can write this on request (the migrator), if anyone wants it. If they don't, their annotation class stays the same as they had, and they see annotations in the annotations tab and comments in the comments tab. If they want to benefit from seeing them in the same tab, we'll explain what code to write to merge their data -- you'll have an ordering issue as well in there, since newly added comments (as a result of migrated annotations) will be at the end of the comments list, not "in between" according to when they were added :).
This solution will ensure that both "annotation" and "comment" IDs are in the same namespace and are unique. This also ensures that: - the replyTo field points to a proper object ID of class XWikiComments - the html IDs are unique in the page so that the permalinks and anchors for jumping to the annotation and back to the comments tab work - the comments are naturally sorted by ID
General downside of solution 1: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
why? as I mentioned, this would be just one use case (using comments class for annotations), if anyone wants to do differently, they can, and they need to accept the fact that they won't see annotations in the comments tab.
= Approach 2 =
The merging solution has a few problems of it's own:
a) The annotation service returns java object Annotations, while the commentsinline.vm works with XWiki API objects. To avoid this problem, we can just do what the old AnnotationsTab did, and that is to directly get the XWiki objects stored in the page using the class configured in the annotations config. Downside: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
b) Merging things means that we keep both the comments and annotations as separate entities. This means that each have their own ID namespace, causing collisions for the replyTo and permalink features. To avoid this, we would have to do some not-so-nice tricks and mark annotations ID (like "annotation1") so that they are separated from regular comments IDs (when used in the replyTo field).
b.1) One solution would be to change the replyTo field's type from Number to String so that we can store this separation. Downside1: This still requires a migration. Downside2: because this means to use the solution for a), we still loose the ability to change the annotation backend.
b.2)The other solution would be to use the annotation service API when getting the list of annotations and make a convention when an annotation is created so that it's numeric ID starts from a very large number (like 1.000.000 or more). Downside: Same as problem a): we have to work with 2 types and lots of "IF statements" when processing the comments. Ex: One type has comment.number (for comments), while the other one has comment.id (for annotations). Same thing for dates: comment.getProperty('date').value vs comment.date.
General downside of solution2: Since they are merged and no longer naturally sorted by object ID, the comments and annotations also need to be sorted by date.
I almost read all this, but I had started this thread of thought before and I agree it's highly complicated compared to solution 1.
= Conclusion=
As I look more into the problem, it does seem that the first approach is the best, having the least number of compromises and doing a better job at semantically merging the two concepts into one.
Do you agree?
+1 for solution 1, with the mentions I made above. In short, I see solution 1 as the following steps: 1/ enhance default XWiki.XWikiComments class with annotations fields (selected text, context, annotation state) 2/ change _default_ annotations class to this XWiki.XWikiComments 3/ disable annotations tab by default 3.1/ polish a bit the comments tab to display new fields of annotations, etc potentially with a migrator to transform all AnnotationCode.AnnotationClass annotations to XWiki.XWikiComments annotations, but not mandatory since not doing so doesn't loose data, it just doesn't display it in the comments tab. This way we keep all the benefits of the annotations system, we just implement a particularization of it in the default XE. Feels quite easy-ish and elegant like this, to me, I wonder if I'm missing a detail (I must be missing a detail). Thanks, Anca
Thanks for your feedback, Eduard
On Fri, Feb 17, 2012 at 11:43 AM, Jerome Velociter<jerome@winesquare.net>wrote:
Le 16 févr. 2012 18:38, "Eduard Moraru"<enygma2002@gmail.com> a écrit :
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their work with minor changes.
A summary of the changes contained by the pull request are described in the jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need to do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked up by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT? I'm tending to prefer a proper migration. I've played in the past with aggregation of both classes on a small "recent reviews" macro, and I recall some (non-trivial) HQL queries were a pain to write, when doable in a single query at all. I can look for specific examples if needed. I fear that if we let both classes live together, some potential future UI or service or whatever that exposes boths in a unified manner might be harder to implement.
Jérôme
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
On Fri, Feb 17, 2012 at 12:54 PM, Anca Luca <lucaa@xwiki.com> wrote:
Actually I was replying to Guillaume and I was thinking about the same set of issues that you mentioned for 2/.
In short, it feels to me that the merging with comments is a particularization of the annotation system, which we could make by default in XE, but still allow people that want to change it to change it, with a bit of code / knowledge about what they're doing. I think very little people used annotations let alone customized the annotations class, in the default XE, so, using the 80/20 rule, we can do it.
Yes, exactly that :)
On 02/17/2012 12:31 PM, Eduard Moraru wrote:
The problems that I am facing now are related to 2 things:
= Approach 1 =
If you use only XWiki.XWikiComments (extended with annotation fileds as the pull request is now), you lose the Annotation feature's capability to specify a different AnnotationClass. This means that, if you want to customize the annotation, you need to extend the XWikiComments class directly, and nothing else.
Why would you? I mean, the way I see it, this should be just a change in the annotations config (from annotationsclass to xwikicomments class) with a bit of hairstyling for the XWikiComments class to contain the things needed for annotations (note that we already have an unused field in XWikiComments designed for that -- highlighttext or something).
What customizers should lose only (in my view) is the possibility to see annotations in the comments tab, that's it. We can even leave the annotations tab (who made it use AnnotationClass objects? because if I remember correctly, when I wrote it, it was using the annotations service to get annotations, regardless of where / how they're stored), and we hide it by default. So displaying it for customizers should only be a matter of setting in the preferences.
This might break existing clients that have provided their own annotation class and will not display their annotations.
As per my comment above, they will just have to enable the annotations tab. Or not even, since annotations tab is enabled by default in the current version, if they don't update their preferences, annotations tab will still stay visible.
Writing a migrator for that would imply looking at the configured annotation class that they have provided, update XWikiComments class with the new fields that might be present in that annotation class and convert the annotation objects to use the updated XWikiComments class instead. Would that be enough?
I think we can write this on request (the migrator), if anyone wants it. If they don't, their annotation class stays the same as they had, and they see annotations in the annotations tab and comments in the comments tab. If they want to benefit from seeing them in the same tab, we'll explain what code to write to merge their data -- you'll have an ordering issue as well in there, since newly added comments (as a result of migrated annotations) will be at the end of the comments list, not "in between" according to when they were added :).
This solution will ensure that both "annotation" and "comment" IDs are in the same namespace and are unique. This also ensures that: - the replyTo field points to a proper object ID of class XWikiComments - the html IDs are unique in the page so that the permalinks and anchors for jumping to the annotation and back to the comments tab work - the comments are naturally sorted by ID
General downside of solution 1: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
why? as I mentioned, this would be just one use case (using comments class for annotations), if anyone wants to do differently, they can, and they need to accept the fact that they won't see annotations in the comments tab.
= Approach 2 =
The merging solution has a few problems of it's own:
a) The annotation service returns java object Annotations, while the commentsinline.vm works with XWiki API objects. To avoid this problem, we can just do what the old AnnotationsTab did, and that is to directly get the XWiki objects stored in the page using the class configured in the annotations config. Downside: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
b) Merging things means that we keep both the comments and annotations as separate entities. This means that each have their own ID namespace, causing collisions for the replyTo and permalink features. To avoid this, we would have to do some not-so-nice tricks and mark annotations ID (like "annotation1") so that they are separated from regular comments IDs (when used in the replyTo field).
b.1) One solution would be to change the replyTo field's type from Number to String so that we can store this separation. Downside1: This still requires a migration. Downside2: because this means to use the solution for a), we still loose the ability to change the annotation backend.
b.2)The other solution would be to use the annotation service API when getting the list of annotations and make a convention when an annotation is created so that it's numeric ID starts from a very large number (like 1.000.000 or more). Downside: Same as problem a): we have to work with 2 types and lots of "IF statements" when processing the comments. Ex: One type has comment.number (for comments), while the other one has comment.id (for annotations). Same thing for dates: comment.getProperty('date').value vs comment.date.
General downside of solution2: Since they are merged and no longer naturally sorted by object ID, the comments and annotations also need to be sorted by date.
I almost read all this, but I had started this thread of thought before and I agree it's highly complicated compared to solution 1.
= Conclusion=
As I look more into the problem, it does seem that the first approach is the best, having the least number of compromises and doing a better job at semantically merging the two concepts into one.
Do you agree?
+1 for solution 1, with the mentions I made above.
In short, I see solution 1 as the following steps: 1/ enhance default XWiki.XWikiComments class with annotations fields (selected text, context, annotation state) 2/ change _default_ annotations class to this XWiki.XWikiComments 3/ disable annotations tab by default 3.1/ polish a bit the comments tab to display new fields of annotations, etc
potentially with a migrator to transform all AnnotationCode.AnnotationClass annotations to XWiki.XWikiComments annotations, but not mandatory since not doing so doesn't loose data, it just doesn't display it in the comments tab.
IMO we should provide the migrator Jerome
This way we keep all the benefits of the annotations system, we just implement a particularization of it in the default XE.
Feels quite easy-ish and elegant like this, to me, I wonder if I'm missing a detail (I must be missing a detail).
Thanks, Anca
Thanks for your feedback, Eduard
On Fri, Feb 17, 2012 at 11:43 AM, Jerome Velociter<jerome@winesquare.net>wrote:
Le 16 févr. 2012 18:38, "Eduard Moraru"<enygma2002@gmail.com> a écrit :
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their
work
with minor changes.
A summary of the changes contained by the pull request are described in
the
jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need
to
do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked
up
by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
I'm tending to prefer a proper migration. I've played in the past with aggregation of both classes on a small "recent reviews" macro, and I recall some (non-trivial) HQL queries were a pain to write, when doable in a single query at all. I can look for specific examples if needed. I fear that if we let both classes live together, some potential future UI or service or whatever that exposes boths in a unified manner might be harder to implement.
Jérôme
Thanks, Eduard
---------- [1] https://github.com/xwiki/xwiki-platform/pull/34 [2] http://jira.xwiki.org/browse/XWIKI-7540 _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
-- Jérôme Velociter Winesquare http://www.winesquare.net/
Hi Anca, Thanks for your feedback. Please read below... On Fri, Feb 17, 2012 at 1:54 PM, Anca Luca <lucaa@xwiki.com> wrote:
Actually I was replying to Guillaume and I was thinking about the same set of issues that you mentioned for 2/.
In short, it feels to me that the merging with comments is a particularization of the annotation system, which we could make by default in XE, but still allow people that want to change it to change it, with a bit of code / knowledge about what they're doing. I think very little people used annotations let alone customized the annotations class, in the default XE, so, using the 80/20 rule, we can do it.
On 02/17/2012 12:31 PM, Eduard Moraru wrote:
The problems that I am facing now are related to 2 things:
= Approach 1 =
If you use only XWiki.XWikiComments (extended with annotation fileds as the pull request is now), you lose the Annotation feature's capability to specify a different AnnotationClass. This means that, if you want to customize the annotation, you need to extend the XWikiComments class directly, and nothing else.
Why would you? I mean, the way I see it, this should be just a change in the annotations config (from annotationsclass to xwikicomments class) with a bit of hairstyling for the XWikiComments class to contain the things needed for annotations (note that we already have an unused field in XWikiComments designed for that -- highlighttext or something).
What customizers should lose only (in my view) is the possibility to see annotations in the comments tab, that's it. We can even leave the annotations tab (who made it use AnnotationClass objects? because if I remember correctly, when I wrote it, it was using the annotations service to get annotations, regardless of where / how they're stored
Yes, you are right. I was mislead by the fact that the annotations count is decided based on the objects on the page. Seems to have been a little hack that is easily fixable though.
), and we hide it by default. So displaying it for customizers should only be a matter of setting in the preferences.
This might break existing clients that have provided their own annotation class and will not display their annotations.
As per my comment above, they will just have to enable the annotations tab. Or not even, since annotations tab is enabled by default in the current version, if they don't update their preferences, annotations tab will still stay visible.
It makes a lot of sense when you look at it that way.
Writing a migrator for that
would imply looking at the configured annotation class that they have provided, update XWikiComments class with the new fields that might be present in that annotation class and convert the annotation objects to use the updated XWikiComments class instead. Would that be enough?
I think we can write this on request (the migrator), if anyone wants it. If they don't, their annotation class stays the same as they had, and they see annotations in the annotations tab and comments in the comments tab. If they want to benefit from seeing them in the same tab, we'll explain what code to write to merge their data -- you'll have an ordering issue as well in there, since newly added comments (as a result of migrated annotations) will be at the end of the comments list, not "in between" according to when they were added :).
Yes, I forgot about that. Will have 2 options here when the migration will be run: 1. Rearrange only once the comment IDs, sorting the comments by date 2. Do the sorting at display time (either in velocity in commentsinline.vm or in the API in XWikiDocument.getComments()), every time, in the likelihood that the comments ID order might be disturbed by such a migration (or anything else, for the matter). Most likely the API would be best since getComments() should order by date anyway instead of id. Even if it's an in-memory operation and the comments are usually already naturally sorted, I wonder if would be a considerable performance penalty. I think option 1 here is most likely the best fit for the problem at hand.
This solution will ensure that both "annotation" and "comment" IDs are in the same namespace and are unique. This also ensures that: - the replyTo field points to a proper object ID of class XWikiComments - the html IDs are unique in the page so that the permalinks and anchors for jumping to the annotation and back to the comments tab work - the comments are naturally sorted by ID
General downside of solution 1: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
why? as I mentioned, this would be just one use case (using comments class for annotations), if anyone wants to do differently, they can, and they need to accept the fact that they won't see annotations in the comments tab.
= Approach 2 =
The merging solution has a few problems of it's own:
a) The annotation service returns java object Annotations, while the commentsinline.vm works with XWiki API objects. To avoid this problem, we can just do what the old AnnotationsTab did, and that is to directly get the XWiki objects stored in the page using the class configured in the annotations config. Downside: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
b) Merging things means that we keep both the comments and annotations as separate entities. This means that each have their own ID namespace, causing collisions for the replyTo and permalink features. To avoid this, we would have to do some not-so-nice tricks and mark annotations ID (like "annotation1") so that they are separated from regular comments IDs (when used in the replyTo field).
b.1) One solution would be to change the replyTo field's type from Number to String so that we can store this separation. Downside1: This still requires a migration. Downside2: because this means to use the solution for a), we still loose the ability to change the annotation backend.
b.2)The other solution would be to use the annotation service API when getting the list of annotations and make a convention when an annotation is created so that it's numeric ID starts from a very large number (like 1.000.000 or more). Downside: Same as problem a): we have to work with 2 types and lots of "IF statements" when processing the comments. Ex: One type has comment.number (for comments), while the other one has comment.id (for annotations). Same thing for dates: comment.getProperty('date').**value vs comment.date.
General downside of solution2: Since they are merged and no longer naturally sorted by object ID, the comments and annotations also need to be sorted by date.
I almost read all this, but I had started this thread of thought before and I agree it's highly complicated compared to solution 1.
= Conclusion=
As I look more into the problem, it does seem that the first approach is the best, having the least number of compromises and doing a better job at semantically merging the two concepts into one.
Do you agree?
+1 for solution 1, with the mentions I made above.
In short, I see solution 1 as the following steps: 1/ enhance default XWiki.XWikiComments class with annotations fields (selected text, context, annotation state) 2/ change _default_ annotations class to this XWiki.XWikiComments 3/ disable annotations tab by default 3.1/ polish a bit the comments tab to display new fields of annotations, etc
potentially with a migrator to transform all AnnotationCode.AnnotationClass annotations to XWiki.XWikiComments annotations, but not mandatory since not doing so doesn't loose data, it just doesn't display it in the comments tab.
This way we keep all the benefits of the annotations system, we just implement a particularization of it in the default XE.
Feels quite easy-ish and elegant like this, to me, I wonder if I'm missing a detail (I must be missing a detail).
Thanks, Anca
Yes, sounds good. So I`m left with polishing the comment display and seeing how I should make the migrator. We should be good to go very soon. Thanks, Eduard
Thanks for your feedback, Eduard
On Fri, Feb 17, 2012 at 11:43 AM, Jerome Velociter<jerome@winesquare.** net <jerome@winesquare.net>>wrote:
Le 16 févr. 2012 18:38, "Eduard Moraru"<enygma2002@gmail.com> a écrit :
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their
work
with minor changes.
A summary of the changes contained by the pull request are described in
the
jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need
to
do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked
up
by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
I'm tending to prefer a proper migration. I've played in the past with aggregation of both classes on a small "recent reviews" macro, and I recall some (non-trivial) HQL queries were a pain to write, when doable in a single query at all. I can look for specific examples if needed. I fear that if we let both classes live together, some potential future UI or service or whatever that exposes boths in a unified manner might be harder to implement.
Jérôme
Thanks,
Eduard
---------- [1] https://github.com/xwiki/**xwiki-platform/pull/34<https://github.com/xwiki/xwiki-platform/pull/34> [2] http://jira.xwiki.org/browse/**XWIKI-7540<http://jira.xwiki.org/browse/XWIKI-7540> ______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
______________________________**_________________
devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
Hi devs, I`ve updated the pull request and pushed a migration script [1], but I`d like a bit of help on 2 issues that I am facing regarding it: 1. Since I have already updated XWiki.getCommentsClass() [2] to add the new fields to the XWikiComments class, I am wondering if I need to do that too in the migration script. If you look at the script that I have pushed, you can see that I have done it [3], but, while testing, it seems that the XWikiComments class is already updated, probably due to XWiki.getCommentsClass() that gets called before the migration. So the question is whether I should keep the updating of XWikiComments in the script or just leave it to XWiki.getCommentsClass()? 2. For some reason, the changes done in the migration script are not saved to the database. I use session.update(...) and session.delete(...) to store my changes, but they don`t seem to be committed to the DB. For instance, the query in my sortCommentsAndReassignObjectNumbers(...) method [4] does not see the objects modified by my previous updateExistingAnnotations(...) method [5]. I must be missing some Hibernate-specific detail, or maybe I am not managing correctly the transaction. Can someone please have a look at the script [1] and point me in the right direction? Thanks, Eduard [1] https://github.com/xwiki/xwiki-platform/pull/34/files#diff-6 [2] https://github.com/xwiki/xwiki-platform/pull/34/files#diff-5 [3] https://github.com/xwiki/xwiki-platform/pull/34/files#L6R109 [4] https://github.com/xwiki/xwiki-platform/pull/34/files#L6R202 [5] https://github.com/xwiki/xwiki-platform/pull/34/files#L6R156 On Fri, Feb 17, 2012 at 5:19 PM, Eduard Moraru <enygma2002@gmail.com> wrote:
Hi Anca,
Thanks for your feedback.
Please read below...
On Fri, Feb 17, 2012 at 1:54 PM, Anca Luca <lucaa@xwiki.com> wrote:
Actually I was replying to Guillaume and I was thinking about the same set of issues that you mentioned for 2/.
In short, it feels to me that the merging with comments is a particularization of the annotation system, which we could make by default in XE, but still allow people that want to change it to change it, with a bit of code / knowledge about what they're doing. I think very little people used annotations let alone customized the annotations class, in the default XE, so, using the 80/20 rule, we can do it.
On 02/17/2012 12:31 PM, Eduard Moraru wrote:
The problems that I am facing now are related to 2 things:
= Approach 1 =
If you use only XWiki.XWikiComments (extended with annotation fileds as the pull request is now), you lose the Annotation feature's capability to specify a different AnnotationClass. This means that, if you want to customize the annotation, you need to extend the XWikiComments class directly, and nothing else.
Why would you? I mean, the way I see it, this should be just a change in the annotations config (from annotationsclass to xwikicomments class) with a bit of hairstyling for the XWikiComments class to contain the things needed for annotations (note that we already have an unused field in XWikiComments designed for that -- highlighttext or something).
What customizers should lose only (in my view) is the possibility to see annotations in the comments tab, that's it. We can even leave the annotations tab (who made it use AnnotationClass objects? because if I remember correctly, when I wrote it, it was using the annotations service to get annotations, regardless of where / how they're stored
Yes, you are right. I was mislead by the fact that the annotations count is decided based on the objects on the page. Seems to have been a little hack that is easily fixable though.
), and we hide it by default. So displaying it for customizers should only be a matter of setting in the preferences.
This might break existing clients that have provided their own annotation class and will not display their annotations.
As per my comment above, they will just have to enable the annotations tab. Or not even, since annotations tab is enabled by default in the current version, if they don't update their preferences, annotations tab will still stay visible.
It makes a lot of sense when you look at it that way.
Writing a migrator for that
would imply looking at the configured annotation class that they have provided, update XWikiComments class with the new fields that might be present in that annotation class and convert the annotation objects to use the updated XWikiComments class instead. Would that be enough?
I think we can write this on request (the migrator), if anyone wants it. If they don't, their annotation class stays the same as they had, and they see annotations in the annotations tab and comments in the comments tab. If they want to benefit from seeing them in the same tab, we'll explain what code to write to merge their data -- you'll have an ordering issue as well in there, since newly added comments (as a result of migrated annotations) will be at the end of the comments list, not "in between" according to when they were added :).
Yes, I forgot about that. Will have 2 options here when the migration will be run: 1. Rearrange only once the comment IDs, sorting the comments by date 2. Do the sorting at display time (either in velocity in commentsinline.vm or in the API in XWikiDocument.getComments()), every time, in the likelihood that the comments ID order might be disturbed by such a migration (or anything else, for the matter). Most likely the API would be best since getComments() should order by date anyway instead of id. Even if it's an in-memory operation and the comments are usually already naturally sorted, I wonder if would be a considerable performance penalty.
I think option 1 here is most likely the best fit for the problem at hand.
This solution will ensure that both "annotation" and "comment" IDs are in the same namespace and are unique. This also ensures that: - the replyTo field points to a proper object ID of class XWikiComments - the html IDs are unique in the page so that the permalinks and anchors for jumping to the annotation and back to the comments tab work - the comments are naturally sorted by ID
General downside of solution 1: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
why? as I mentioned, this would be just one use case (using comments class for annotations), if anyone wants to do differently, they can, and they need to accept the fact that they won't see annotations in the comments tab.
= Approach 2 =
The merging solution has a few problems of it's own:
a) The annotation service returns java object Annotations, while the commentsinline.vm works with XWiki API objects. To avoid this problem, we can just do what the old AnnotationsTab did, and that is to directly get the XWiki objects stored in the page using the class configured in the annotations config. Downside: you lose the ability to change the annotation backend, since you just look at XWiki objects in the page.
b) Merging things means that we keep both the comments and annotations as separate entities. This means that each have their own ID namespace, causing collisions for the replyTo and permalink features. To avoid this, we would have to do some not-so-nice tricks and mark annotations ID (like "annotation1") so that they are separated from regular comments IDs (when used in the replyTo field).
b.1) One solution would be to change the replyTo field's type from Number to String so that we can store this separation. Downside1: This still requires a migration. Downside2: because this means to use the solution for a), we still loose the ability to change the annotation backend.
b.2)The other solution would be to use the annotation service API when getting the list of annotations and make a convention when an annotation is created so that it's numeric ID starts from a very large number (like 1.000.000 or more). Downside: Same as problem a): we have to work with 2 types and lots of "IF statements" when processing the comments. Ex: One type has comment.number (for comments), while the other one has comment.id (for annotations). Same thing for dates: comment.getProperty('date').**value vs comment.date.
General downside of solution2: Since they are merged and no longer naturally sorted by object ID, the comments and annotations also need to be sorted by date.
I almost read all this, but I had started this thread of thought before and I agree it's highly complicated compared to solution 1.
= Conclusion=
As I look more into the problem, it does seem that the first approach is the best, having the least number of compromises and doing a better job at semantically merging the two concepts into one.
Do you agree?
+1 for solution 1, with the mentions I made above.
In short, I see solution 1 as the following steps: 1/ enhance default XWiki.XWikiComments class with annotations fields (selected text, context, annotation state) 2/ change _default_ annotations class to this XWiki.XWikiComments 3/ disable annotations tab by default 3.1/ polish a bit the comments tab to display new fields of annotations, etc
potentially with a migrator to transform all AnnotationCode.AnnotationClass annotations to XWiki.XWikiComments annotations, but not mandatory since not doing so doesn't loose data, it just doesn't display it in the comments tab.
This way we keep all the benefits of the annotations system, we just implement a particularization of it in the default XE.
Feels quite easy-ish and elegant like this, to me, I wonder if I'm missing a detail (I must be missing a detail).
Thanks, Anca
Yes, sounds good. So I`m left with polishing the comment display and seeing how I should make the migrator. We should be good to go very soon.
Thanks, Eduard
Thanks for your feedback, Eduard
On Fri, Feb 17, 2012 at 11:43 AM, Jerome Velociter<jerome@winesquare.** net <jerome@winesquare.net>>wrote:
Le 16 févr. 2012 18:38, "Eduard Moraru"<enygma2002@gmail.com> a écrit
:
Hi devs,
Based on the work done by Anca and Sorin doring the XWiki 2011 Seminar Hackaton, I`ve made the following pull request [1] to integrate their
work
with minor changes.
A summary of the changes contained by the pull request are described in
the
jira issue [2].
The problem at the current stage, as Jerome also hinted, is that we need
to
do a migration script to make the existing annotations (in an upgrade scenario) use the XWikiComments class instead so that they can be picked
up
by commentsinline.vm. However, this might lose the possibility to provide custom annotations.
An alternative would be to make commentsinline.vm use the annotation service and handle and retrieve both Annotation and XWikiComment objects. This way, the current annotations should need no migration script since they are using a class configured in the AnnotationConfig page that the annotation service knows how to handle.
WDYT?
I'm tending to prefer a proper migration. I've played in the past with aggregation of both classes on a small "recent reviews" macro, and I recall some (non-trivial) HQL queries were a pain to write, when doable in a single query at all. I can look for specific examples if needed. I fear that if we let both classes live together, some potential future UI or service or whatever that exposes boths in a unified manner might be harder to implement.
Jérôme
Thanks,
Eduard
---------- [1] https://github.com/xwiki/**xwiki-platform/pull/34<https://github.com/xwiki/xwiki-platform/pull/34> [2] http://jira.xwiki.org/browse/**XWIKI-7540<http://jira.xwiki.org/browse/XWIKI-7540> ______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
______________________________**_________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/**mailman/listinfo/devs<http://lists.xwiki.org/mailman/listinfo/devs>
participants (6)
-
Anca Luca -
Eduard Moraru -
Guillaume Lerouge -
Jerome Velociter -
Ludovic Dubost -
Marius Dumitru Florea