Production annotation manager, for Komodo. This file is free of all rights (a.k.a., public domain). This file contains miscellaneous notes and a task list for a production annotation manager, for Komodo. It was meant to be used for my Komodo extensibility challenge entry, but I don't know much about Firefox/Mozilla extensions, XUL is far too complicated, there is not much documentation for XUL with Komodo, and I just don't have enough time to learn about all this (not that I would, if I had more time, now that I know how complicated this is). Short description: This extension permits to annotate a document, during production. You can follow the text age, you can set statuses (validated text/code -with multiple levels of validation, and generation of reports-, workaround code, duplicate code, etc.), properties (author of a piece of code, origin, license, maintainer, etc.), and arbitrary comments. It generally replace, standardize, and manage piece of comments you would otherwise add as plain text in your text/code. Misc notes ################################################################################ - Statuses: "Code to recheck" (@Todo Check...), "Non-validated code to reread" (@Todo Check.), "New code" (very recent code, not validated), "Recent code" (not validated), "Old code" (@Todo Check.; still not validated), "Validated code" (@Todo Check.), "Suspicious code" (code to reread/recheck), "Erroneous code" (bogus code? -I prefer to use "erroneous", but we have to be specific), "Temporary code", "Workaround code", "Incomplete code", "Duplicate code" (with link to main code, if applicable?), etc. Maybe more QA-oriented statuses, notably oriented to accessibility, usability and ergonomy (though these statuses might not be reflected as well, in code, than in the technical documentation...). - Properties: for example, to specify the author, maintainer, origin of the code, license, etc. (though it should be oriented to internal properties, for use in the code editor... not for publication...). Task list ################################################################################ (Note that I didn't really reread this list, and that there might be some consistency problems, due to the fact I started added notes early, but didn't modified them as my ideas evolved). Tasks for the first release ================================================================================ High-priority tasks for the first release -------------------------------------------------------------------------------- - Cool/geeky highlight when currently typing (new code -see Text age reporter). - Soft highlight (low-contrast backgrounds), to avoid diminishing readability. - Highlight character by character, and use icons to highlight lines ("contains recent code", "contains old code", "validated line", etc.). - Check how to handle current line highlighting... (except at the end of line, it will mostly be lost, by default, if we use background colors for status highlighting). Maybe we can try to replace it by something else, as a work around... (frame, use of line/icon border, etc.). - Try not to get in the way of other highlighting styles, notably for syntax errors (well, they use mostly underlines, but they should stay perfectly visible.). - Makes the code age depends on date. - Use XML for status files. - Use the right-click menu to attach notes to the code. - Option to change status automatically to "to recheck" (with a special flag, or something, to say the status was changed automatically -we should also keep the previous manual status, if there is any, and probably the previous automatic status too). - Warning about accessibility (low-contrast background, by default, notably). - Take into account the (reported) problem with Komodo, when the cursor is located just before a closing parenthesis, and the user is typing code: some characters become dark red (the style associated with the parentheses, when touching them), for some instants. It might interfere with the "new code" highlighting rules... (as a workaround, maybe deactivate the style of parentheses, when touching them, when typing...). Medium-priority tasks for the first release -------------------------------------------------------------------------------- - Support undo/redo, same changes (removing something, and readding it exactly as it was before), trivial changes (though it is hard to define... whitespaces can matter just as much as they might not... -and even more an languages like Python, where indentation is part of the syntax). - Handle copy-pastes (including moving statuses? in part only? -if the context changes, the code must be at least rechecked). - Permit to use keyboard shortcuts (and permit to configure them). - Create a toolbar. - Permit to configure which colors (and styles), to use for highlighting. - Possibility to attach comments to each status (comments would appear as pop-above). - Possibility to list the comments (that is, in a separate document/window, not just as part of the current document -well, we should still be able to manager the comments from this view). - File, zone, block, line, word bookmarks, with comments (why it was bookmarked). Low-priority tasks for the first release -------------------------------------------------------------------------------- - Internationalize the extension (English, French). - Larger font-size for very recent code? (it there is no readability problem). - Full history of status changes, and changelog in relation to the document (probably start by writing a debug log file). - Possibility to attach properties to each status (author, todo, etc.). - Create a menu. - Per-file and per-project status. - Inherit status (if all lines from a file are validated, the file can inherit the "validated" status). - Possibility to override inherited statuses (but both informations should be available... for example, all the lines from the file are validated, so the file inherits the "validated" status, but you would like to recheck the file globally, so you set the manual status "to recheck"...). High-priority tasks ================================================================================ - Recovery measures if the file and associated status file are not synchronized (for example, if the file was edited in an external editor, or some backup of either the file or the status file was restored, but not both...). For now, just check the file hash, and modification time. In the future, try to recover as many informations as possible, and warn the user about any decision and problem. - Per-code block status. - Easy sharing/centralization (possibility to put in CVS/SVN, and to easily avoid distributing the annotations in public versions), with per-file status files, possibility to group status files, for projects, possibility to include in a Komodo project, etc.). Medium-priority tasks ================================================================================ - Support some kind of priority, to improve the code (and, as a consequence, its status). - Add todos, along comments? (there would be automatic todos, generated depending on the status, but we might define manual todos, with more informations, in a more standardized format). - Along with statuses (or should we merge this?), support some checklists... like "proper coding standards", "proper integration", "proper syntax", "covered by test cases", etc. - Optimize for large files and large list of statuses and comments. - Generate file lists, with statistics (percentages, number of characters/words/lines/files, depending on statuses, etc.). - Permit to make the code age depend, in part or totally, on the real use of files... (amount of time with file open, active, number/amount of change in file, etc.). For example, a code which has been written recently, and the file has been left alone for three years, then, when reopening the file, the code will still be marked as recent (well, we will of course permit to access date informations). - Third party code review (QA, pair programming, etc.). Possibility to create statuses depending on the coder, and merge all this in global status informations (or something like this). - Permit to create code groups, to define a status, from anything, including arbitrary selections. - Handle status collisions. If a more general part has an higher status than a more local part... (option to solve automatically by lowering status). Also, if some code parts overlap only partially... Low-priority tasks ================================================================================ - Maybe permit to separate private, internal annotations (that is, which really would not be of any use to the public), and any other annotation which could help the public using or modifying the code. - Permit to customize the menu and the toolbar (which option to list, icons, text, etc.). - Handle source code revisions (the possibility to use versioned sets of statuses, notably to reset the status of some file to "Code to recheck", for a new revision, but to keep available, the status from previous revisions). - Support the possibility to share status in real time (save all changes immediately, so they can be uploaded/shared immediately, and permit to export only the changes, for faster upload). Note we will have to synchronise the files too (use a temporary file, and export only the changes). - Time tracker (generic one -independent from the status management-, and one depending on code and status changes). Production annotation manager module: Text age reporter ################################################################################ The text age reporter can highlight the text depending on its age. It supports three life periods: - new text: text which has just been entered or modified (by default, it stays in this state for about thirty seconds), which should help you better spot typos; - recent text: text which has been entered or modified recently (by default, it stays in this state for about two days), which should help you better spot recent regressions and bugs; - old text: older text, which has not been modified recently. A few behaviour notes: - If you modify new text, and there is some unmodified new text around it, then the unmodified zone will stay in the new state for a bit longer. - New text moves to the recent text state, character by character. - By default, the new text state is saved as recent text. It means that if you close a file, or Komodo, while new text is highlighted, then, even if you reopen the file a few seconds later, the text will have moved to the recent text state. - Recent text will not move to the old text state, as long as the file it is in, is not closed (or Komodo is closed). - The precise age of the text is not saved (the text age informations are saved per zone). - For recent text, by default, the text age reporter counts the time during which the file was closed, as part of the age.