Wiki source code of License Review Tool Requirements vs XWiki
Last modified by Ludovic Dubost on 2020/07/10 17:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | == Requirements for license-review process == | ||
| 2 | |||
| 3 | ==== Must have ==== | ||
| 4 | |||
| 5 | * Ability to submit a license for review | ||
| 6 | |||
| 7 | ? a license can be created in an app and meta-data can be filed in by the requesting organization | ||
| 8 | |||
| 9 | [[image:osi-license-info.png||height="412" width="800"]] | ||
| 10 | |||
| 11 | Licenses are nicely listed and searchable in an "XWiki Livetable". | ||
| 12 | |||
| 13 | [[image:osi-license-review.png||height="382" width="800"]] | ||
| 14 | |||
| 15 | * Being able to immediately identify the current state of review for a license (eg. "approved", "rejected", "new", "being redrafted", "invalid", "rejected", etc.) | ||
| 16 | |||
| 17 | ? metadata field includes a status | ||
| 18 | |||
| 19 | * Ability to submit updated revisions of a license, without destroying previous ones or associated history. (Licenses often go through multiple rounds of revisions or drafts based on feedback received.) | ||
| 20 | |||
| 21 | ? content of the updated version can be updated. Annotation system will still recognize the text that did not change and will also recognized changed text by changing the color of the annotation. | ||
| 22 | |||
| 23 | * Ability to comment on specific sections/words/lines of a given draft of license. (Sections of licenses that have been revised are areas of interest) | ||
| 24 | |||
| 25 | ? ability to use XWiki's annotation/comment system allowing to comment the license. In the prototype we have added a notion of TASK which would be associated optionally to annotations in order to list issues that require a resolution. The UI would allow to see all unresolved Issues. | ||
| 26 | |||
| 27 | [[image:osi-license-annotations.png]] | ||
| 28 | |||
| 29 | Annotations/Comments are threaded and can launch a discussion around the annotation. The tasks would also have their own comments which can also be threaded. | ||
| 30 | |||
| 31 | [[image:osi-task.png]] | ||
| 32 | |||
| 33 | * Ability to comment on a license in a general sense | ||
| 34 | |||
| 35 | ? annotation/comments can be at the bottom and are threaded. | ||
| 36 | |||
| 37 | * Ability to moderate discussions (including removing comments, editing comments, banning users) | ||
| 38 | |||
| 39 | ? XWiki's standard user management and comment management can be used. | ||
| 40 | |||
| 41 | [[image:osi-comments.png]] | ||
| 42 | |||
| 43 | * Ability to close the process with the publication of an accompanying rationale document | ||
| 44 | |||
| 45 | ? a "report" wysiwyg field is being added to the License Review. Also a workflow is enabled allowing to move the document to a "moderation" stage. In this stage only "moderators" can edit the document with the objective to write the report. | ||
| 46 | |||
| 47 | [[image:osi-license-report.png]] | ||
| 48 | |||
| 49 | * Discussions must be publicly accessible, without authentication | ||
| 50 | |||
| 51 | ? All is public on the OSI sub-wiki | ||
| 52 | |||
| 53 | * Users must authenticate and maintain a consistent identity in order to comment/participate in the process | ||
| 54 | |||
| 55 | ? OSI Wiki authentication would be used | ||
| 56 | |||
| 57 | * Time-stamping of all comments and submissions | ||
| 58 | |||
| 59 | ? XWiki has a full history mecanism on ALL changes. | ||
| 60 | |||
| 61 | [[image:osi-history.png]] | ||
| 62 | |||
| 63 | * Entirely separate discussions for each license | ||
| 64 | |||
| 65 | ? Each license has it's own area with it's own tasks associated. | ||
| 66 | |||
| 67 | * Discussions must be archiveable and available to reference through linking | ||
| 68 | |||
| 69 | ? A separate archive area or even archive wiki could be made available to move the content. The license "space" could be exported to a XAR file and deleted form the wiki (but could be later reimported) | ||
| 70 | |||
| 71 | * Easy to learn and use by non-technical users | ||
| 72 | |||
| 73 | ? The UI proposed has the objective to be easy to discover and understand. Everyting is happening through the XWiki UI | ||
| 74 | |||
| 75 | * Must not assume experience with specific technical tools (i.e. requirement to use Git, XML, or a specific programming language, etc.) | ||
| 76 | |||
| 77 | ? Everything is happening through the XWiki UI | ||
| 78 | |||
| 79 | * Tools are principally open source | ||
| 80 | |||
| 81 | ? XWiki is 100% Open Source, already OSI affiliate and the custom development made can even be published as an extension. | ||
| 82 | |||
| 83 | ((( | ||
| 84 | |||
| 85 | ))) | ||
| 86 | |||
| 87 | ==== Nice to have ==== | ||
| 88 | |||
| 89 | * Ability to cross-reference a different comment in the same or different discussion | ||
| 90 | |||
| 91 | (% class="box warningmessage" %) | ||
| 92 | ((( | ||
| 93 | ⚠ This requirement is not full clear. Comments have permalinks which can be referenced. | ||
| 94 | ))) | ||
| 95 | |||
| 96 | XWiki will have "mentions" for users in the 12.x version (not yet available however) | ||
| 97 | |||
| 98 | * Searchable discussions | ||
| 99 | |||
| 100 | ? XWiki has a full fledge SOLR engine allowing to search all content | ||
| 101 | |||
| 102 | Licences are also searchable in the XWiki Livetable | ||
| 103 | |||
| 104 | * Canonical URIs for each license for review | ||
| 105 | |||
| 106 | ? License Review page has a readable URL | ||
| 107 | |||
| 108 | * Machine-readable output from the license review process (text of the license + metadata such as Author, Date approved, Link to discussion, etc.) | ||
| 109 | |||
| 110 | ? The license review page is available as XML and APIs are available to the whole XWiki content. | ||
| 111 | |||
| 112 | * Low administrative overhead/hosted service (OSI does not have a good track record of hosting/maintaining new services) | ||
| 113 | |||
| 114 | ? No additional service needed | ||
| 115 | |||
| 116 | * Previous license review emails can be added so that all license reviews are in the same place (we may need to engage someone separately to complete a migration) | ||
| 117 | |||
| 118 | (% class="box warningmessage" %) | ||
| 119 | ((( | ||
| 120 | ⚠ This would require an import which is not fully easy because emails are spread in different archives accross time. Transformation to the exact format of the XWiki tool would also be not easy. An alternate option would be to import the emails in XWiki in each space for older licences just for SOLR based search. This could be less complicated. | ||
| 121 | ))) | ||
| 122 | |||
| 123 | * Configurable notifications in order to watch and follow discussions | ||
| 124 | |||
| 125 | ? XWiki has standard "subscription" based notifications. | ||
| 126 | |||
| 127 | Workflow also sends notification | ||
| 128 | |||
| 129 | * Welcoming to new community members | ||
| 130 | |||
| 131 | ? - tool already in place | ||
| 132 | |||
| 133 | * Badges to easily identify participants to provide context (e.g. OSI board members, long-time community participants, etc.) | ||
| 134 | |||
| 135 | ? - A customization would be needed on the XWiki profile to add a badge based on a metadata. Doable but we need to see where it would be displayed (comments, user edits, etc..) There might be multiple places to configure to show the badge. Alternatively users could modify their photo to include the badge on their profile photo. | ||
| 136 | |||
| 137 | * Not mandatory to use the tool in order to participate in review, i.e., system integrates with an email workflow | ||
| 138 | |||
| 139 | Technically it's feasible to receive send all notifications email to a "license mailing" list. Handling responses would require to study what exactly to do with responses. | ||
| 140 | |||
| 141 | (% class="box warningmessage" %) | ||
| 142 | ((( | ||
| 143 | ⚠ This might be more complicated. A lot of feature would be lost to connect comments to content and to each other. | ||
| 144 | ))) |