[xwiki-devs] [Discussion] Annotations feature current state and roadmap

Hello devs, The current state of the annotation feature in the sandbox can be described by the follwing: * there is a single type of annotation which can be added, using a specific javascript client backed by a rest service. Such an annotation contains an annotation text, the annotated content and its position and this type is highly coupled in the plugin implementation * the backing annotation storage is based on components, currently with an XWiki objects implementation but a different service can be easily created (there is one implemented for Scribo annotations stored in RDF) * for the moment, only xwiki documents and feed entries fetched by the feedreader plugin can be used as targets for annotations (the annotated documents), with the restriction that the content of the document is *not* generated using scripting. A component can be implemented for a new type of document but the current UI (the javascript client) is *specific to xwiki documents* * the javascript client (UI) is only in the state of a prototype: while proving that it works, it is not robust enough and the user experience is poor * annotation creation algorithm seems to perform well in practice, but we should put it to more real-world test (by releasing). Some *requirements* in terms of functionality, in order to make this an extensible and flexible feature, would be to: * be able to have different types of annotations (one to be able to easily specify fields for the annotations to add), with storage as xwiki objects. This needs to be flexible at all levels: UI and storage backend, preferably using xwiki scripting (no jars on the server side, or java coding) so that it can be easily customized. Also, the annotation UI should be thought of as easy to customize and create whatever forms and actions in a light manner. * be able to annotate any type of document (object inside such a document), namely all or any number of text fields in such an object. Preferably this should also be doable only using xwiki scripting or configuration. I would like to propose the following road to perfect this feature: *Version 1.0* (somewhere in the timeframe of XE 2.1 RCs) The aim would be to take feature out of sandbox preserving its current features: allowing to add a specific type of annotation saved as XWiki object on a regular, non scripted XWiki Document. We should: - format, improve comments, generally clean up the current code sandbox to match XWiki coding styles - refactor packages and components to remove some dependencies issues and increase flexibility - simplify flow, stripping out all code which is not strictly needed by the targeted functionality (such as the Feed entry handling code), and make it easily implementable by a component in a distinct jar (so that the Scribo requirements currently implemented can be preserved) - finish the javascript client: robust user interaction, intuitive interface, cleaned up integration with XE - ensure quality assurance process by a well setup battery of tests, unit and functional At this point I propose to have the annotation feature as an installable plugin but not included by default in XE, unless after a few bugfixing cycles. *Version 1.1* (somwhere in the timeframe of XE 2.2, at the beginning of next year) * first iteration on the 2 desired features. At this point one should be able to configure the type of annotation to add, UI should be accomodate this type, backing XWiki storage should be easy to integrate with any annotation storage service (for Scribo requirements), and one should easily set a field in a structured document which would support annotations. (Note that this might require heavy rewrite / refactor of the 1.0 version. We could decide to skip it and go straight to this version, but it would take longer.) * integration of Scribo requirements can be met at this point by setting the configurations according to the Scribo annotation type and target requirements. At this point, if we find appropriate, we could make the decision of including the annotation feature in XE by default *Version 1.2* (future) * finish the 2 requirements, integration with Scribo would be done in the same manner, by specific configuration and storage backend specific implementation. What do you think? For the moment I will focus on version 1's tasks while finding a good architecture to achieve the desired requirements, converting, where necessary, the direction of the development towards that goal. Thanks (for reading this very long mail), Anca