Edgewall Software

Changes between Initial Version and Version 1 of CodeReview/Annotations


Ignore:
Timestamp:
Jun 20, 2011 1:34:31 PM (3 years ago)
Author:
cboos
Comment:

some ideas about content annotations

Legend:

Unmodified
Added
Removed
Modified
  • CodeReview/Annotations

    v1 v1  
     1= Inline annotation of content
     2
     3In the following we try to figure how we could associate manual annotations to any kind of "line oriented" text content.
     4
     5== Editing use cases
     6
     7=== Whole file annotation mode
     8One could imagine a general way of annotating original text-based
     9content in a way similar to the one we handle "citations" (e.g. in the //Reply to// feature of tickets, with the **`> `** line prefixes).
     10
     11This would take any original input and prefix each line (e.g. with **`| `**) and the author of the review could then "split" that content at any point and add some comment in the form of wiki text.
     12
     13E.g. for the original two lines:
     14{{{
     15Code reviews should support configurable workflows
     16(like tickets).
     17}}}
     18//Annotate//ing it would give you a textarea with this content:
     19{{{
     20| Code reviews should support configurable workflows
     21| (like tickets).
     22}}}
     23You could then change this to:
     24{{{
     25| Code reviews should support configurable workflows
     26So this implies that a review is an entity by itself (i.e. a kind Trac
     27resource), as opposed to only metadata for another resource.
     28| (like tickets).
     29One wonders however if this justifies an entire new class of resources
     30or if using a specific "ticket type" wouldn't be enough, assuming one
     31could have a dedicated workflow per type, specific fields per type,
     32as often discussed.
     33}}}
     34
     35Such "annotated content" would then be processed line by line:
     36 1. accumulate the lines of "original" content (which may or may not be 100% identical to the real original content; this may provide the basis of "diff" based annotations useful for suggesting changes in wording, for example)
     37 2. when there are comment lines, group them and associate them to the line number of original content placed above (or below if there's more vertical whitespace at the top than on the bottom); this creates an "annotation"
     38
     39The rendering would proceed nearly as usual, but in addition to the "unicode content" given as input to the renderers (note to self, finish #3332 one day ;-) ), we would also provide a map `{linenum: annotation}`, where an annotation dict would contain several fields like the //comment// lines themselves (to be wiki-rendered in the `RenderingContext` of the codereview object, itself parented in the rendering context of the original resource), the //author// of the comment, and the //created// time  (//after// flag set to `True` if the comment follows the anchored content line)
     40
     41A possible rendering could be:
     42{{{#!div style="border:1px solid #eee"
     43Code reviews should support configurable workflows
     44[[span(style=display: list-item; list-style-type: square; border:1px solid #ddc; border-top: 2px solid #ddc; background:#ffc; font-size: 80%, So this implies that a review is an entity by itself (i.e. a kind Trac resource), as opposed to only metadata for another resource.)]]
     45(like tickets).
     46[[span(style=display: list-item; list-style-type: square; border:1px solid #ddc; border-top: 2px solid #ddc; background:#ffc; font-size: 80%, One wonders however if this justifies an entire new class of resources or if using a specific "ticket type" couldn't be enough, assuming one could have a dedicated workflow per type, specific fields per type, as often discussed.)]]
     47}}}
     48
     49Most existing mimetype renderers ones are line oriented and could therefore be easily extended to support rendering these annotations (e.g. our own patch renderer, the plaintext renderer, the  Pygments renderer, and of course the wiki formatter)
     50
     51=== Annotation editing
     52The "whole file annotation" approach isn't necessarily the only approach. We can imagine finer grained user interfaces, e.g. a la GitHub, clicking on a line in the source browser and adding a paragraph below.
     53
     54In some situations (for source code, even for patches perhaps) this can be even more attractive than the whole page approach. The latter is perhaps only suited to wiki page annotation, after all.
     55
     56Likewise, clicking on an annotation and editing it alone (or perhaps even "replying to" it) should be easy, both from the p.o.v. of the user and to implement, as no modification of the main content is involved here and the anchoring of the annotation remains the same.
     57
     58=== Combined content and annotations changes (//review processing?//)
     59For wiki pages reviews, we could imagine an edit mode in which the page content and its annotations are edited at the same time (responding to a review). In this situation, having a line prefix for the content would be annoying and it would be much better to have the annotations wrapped in `{{{#!review ...}}}` blocks. After parsing, those blocks would be removed from the content and the annotation would be updated separately (based on some `id=...` tagging).
     60
     61Editing our previous example, this would give:
     62{{{
     63Code reviews should support configurable workflows
     64{{{#!review id=1 author="cboos" created="...."
     65So this implies that a review is an entity by itself (i.e. a kind Trac
     66resource), as opposed to only metadata for another resource.
     67}}}
     68(like tickets).
     69{{{#!review id=2 author="cboos" created="...."
     70One wonders however if this justifies an entire new class of resources
     71or if using a specific "ticket type" wouldn't be enough, assuming one
     72could have a dedicated workflow per type, specific fields per type,
     73as often discussed.
     74}}}
     75}}}
     76After modification:
     77{{{
     78Code reviews should support configurable workflows.
     79{{{#!review id=1 author="cboos" created="...."
     80So this implies that a review is an entity by itself (i.e. a kind Trac
     81resource), as opposed to only metadata for another resource.
     82
     83Note the possible ambiguity:
     84 - in a "post-review", the code review is clearly a review
     85   of something (typically a changeset, or a branch)
     86 - in a "pre-review", the change is part of the review
     87   proposal and possibly doesn't exist elsewhere
     88}}}
     89This could be achieved either by generalizing state and workflows
     90to a `codereview` resources, or by using a dedicated type of ticket
     91and have per-worflow type, specific fields per type, etc.
     92}}}
     93After parsing:
     94 - the review block id=1 has been modified; it's still associated to the same line of content (here 1+)
     95 - review block id=2 disappeared, meaning this comment has been addressed (here by incorporating some of it in the main text)
     96
     97The review blocks are removed and the content which gets stored is simply:
     98{{{
     99Code reviews should support configurable workflows.
     100This could be achieved either by generalizing state and workflows
     101to a `codereview` resources, or by using a dedicated type of ticket
     102and have per-worflow type, specific fields per type, etc.
     103}}}
     104
     105Annotation id=1 gets a new version with its new content and new anchor if needed. Note that this mechanism should be very robust, as when the author  moves sections around, the annotations will move alongside with the content.
     106
     107Annotation id=2 gets a new "deleted" version.
     108
     109
     110=== Content changes only, in presence of annotations
     111If instead of the previous combined mode, the author chooses to edit the content alone (or if there's simply no other choice, if the annotated resource is a source file), then we risk to lose the associations between the annotations and the annotated lines.
     112
     113In some cases, it should be possible to update the line numbers by processing the diffs, but in general if the annotated lines are deleted, the annotations become "orphaned" or floating. Maybe they're not relevant anymore, maybe the anchor line has moved, we have no way to know for sure.
     114
     115We can imagine that those annotations become simple "resource" level comments, not anchored anymore to some specific line number. It should even be possible to provide an UI to "reconnect" those comments to a line number in the new version. At least, there should be a link to the last version of the resource where the annotation could be seen in context.