Wiki source code of OpenProject
Last modified by Vincent Massol on 2026/06/03 14:15
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{toc/}} | ||
| 2 | |||
| 3 | = Implementation Details = | ||
| 4 | |||
| 5 | == Must Haves == | ||
| 6 | |||
| 7 | > REQM01: Be able to issue queries to find issues (e.g. JQL for JIRA), including global search in all projects. It's used in lots of places, including on hundreds of pages on xwiki.org | ||
| 8 | |||
| 9 | {{warning}} | ||
| 10 | It's possible to filter (but in much less powerful way than JIRA's JQL, which will be a problem to migrate the thousands of JQL queries existing on xwiki.org) in 2 ways: | ||
| 11 | * Using the advanced search | ||
| 12 | * Using the Filter button in the work package view. | ||
| 13 | |||
| 14 | The later allows to copy the URL and share it. The former doesn't. | ||
| 15 | |||
| 16 | There's also a [[REST API to Query work packages>>https://www.openproject.org/docs/development/concepts/queries/]], including [[setting filters>>https://www.openproject.org/docs/api/filters/]], and there's an [[OP Contrib Macro>>https://github.com/xwiki-contrib/openproject]] that uses that REST API to display work packages. There's also an [[XWiki SAS company OP Pro extension>>https://store.xwiki.com/xwiki/bin/view/Extension/OpenProjectIntegration]] that adds features and which [[documents how to perform filters>>https://store.xwiki.com/xwiki/bin/view/Extension/OpenProjectIntegration#HFilteringforworkpackages]]. | ||
| 17 | {{/warning}} | ||
| 18 | |||
| 19 | > REQM02: Be able to label issues. We're using [[the following labels>>dev:Community.IssueTracker.JIRA.WebHome||anchor="HRule:Usetherightlabels"]] | ||
| 20 | |||
| 21 | Implemented as a [["Labels" custom field>>https://op.xwiki.org/custom_fields]] using a List so that we control the labels that can be used. | ||
| 22 | |||
| 23 | > REQM03: Be able to have several resolutions for issues (Won't fix, Fixed, Duplicate, Solved By, etc.) | ||
| 24 | |||
| 25 | There's no concept of "resolution". Only a concept of "statuses". | ||
| 26 | |||
| 27 | We have 2 options: | ||
| 28 | 1. Fold the concept of resolution inside the concept of statuses. | ||
| 29 | 1. Introduce a custom field for Resolution. See below for custom fields. | ||
| 30 | |||
| 31 | Option 1 has the advantage that we can mark a status entry as being 100% complete and marking the work package as closed. | ||
| 32 | |||
| 33 | If we go with option 2 then there's no relationship between resolution and statuses (we cannot force the user to set a Resolution). Note that there's the concept of "automatic action" but it's limited and cannot be used to solve the problem. See https://op.xwiki.org/admin/custom_actions | ||
| 34 | |||
| 35 | Thus option 1 has been implemented. | ||
| 36 | |||
| 37 | > REQM04: Be able to have categories (components in JIRA parlance) | ||
| 38 | |||
| 39 | Categories are set per project. See for example: | ||
| 40 | * [[Categories for the Contrib Project Template>>https://op.xwiki.org/projects/contrib-project-template/settings/work_packages/categories]] | ||
| 41 | * [[Categories for the LaTeX Project>>https://op.xwiki.org/projects/latex/settings/work_packages/categories]] | ||
| 42 | |||
| 43 | > REQM05: Be able to automatically link GitHub commits with JIRA issues (i.e., links from JIRA to the commits) | ||
| 44 | |||
| 45 | {{error}} | ||
| 46 | Seems it's only possible to [[link to GH PRs>>https://www.openproject.org/docs/system-admin-guide/integrations/github-integration/]]. See https://community.openproject.org/projects/OP/work_packages/OP-19441/activity | ||
| 47 | |||
| 48 | Only the following GH webhook events are supported (all others return a 404 from OP): https://github.com/opf/openproject/blob/v16.6.1/modules/github_integration/lib/open_project/github_integration/hook_handler.rb#L31-L37 | ||
| 49 | |||
| 50 | This means that "push" events (which happen when a commit is pushed) are not supported and we cannot track git commits in OP work packages :( | ||
| 51 | |||
| 52 | For now, you should still commit using the following format: | ||
| 53 | |||
| 54 | {{code language="none"}} | ||
| 55 | OP#<issue number>: <issue title> | ||
| 56 | <* optional additional information> | ||
| 57 | {{/code}} | ||
| 58 | |||
| 59 | For example: | ||
| 60 | |||
| 61 | {{code language="none"}} | ||
| 62 | OP#49: Add a Documentation class for UIXP + add a UIX | ||
| 63 | * Also fix a bug in RenderingMacrosUIX and DocumentationSheet to allow supporting more than 1 UIX | ||
| 64 | {{/code}} | ||
| 65 | {{/error}} | ||
| 66 | |||
| 67 | > REQM06: Be able to have several issue types | ||
| 68 | |||
| 69 | See https://op.xwiki.org/types | ||
| 70 | |||
| 71 | > REQM07: Be able to have graphs to follow, for example, the number of bugs created vs resolved | ||
| 72 | |||
| 73 | {{warning}} | ||
| 74 | Some limited graphs per project: | ||
| 75 | * [[Work package graphs>>https://www.openproject.org/docs/user-guide/project-overview/#work-package-graph-widgets]] using all the existing fields (including custom ones) + ability to set filters on fields | ||
| 76 | * [[Work package overview graphs>>https://www.openproject.org/docs/user-guide/project-overview/#work-package-overview-widget]] | ||
| 77 | * [[Work package table>>https://www.openproject.org/docs/user-guide/project-overview/#work-package-table-widget]] using all the existing fields (including custom ones) + ability to set filters on fields | ||
| 78 | {{/warning}} | ||
| 79 | |||
| 80 | > REQM08: Be able to have REST endpoints to create XWiki macros (e.g., the JIRA macro) or scripting in xwiki pages | ||
| 81 | |||
| 82 | See https://www.openproject.org/docs/api/ | ||
| 83 | |||
| 84 | > REQM09: Be able to have several projects (one for each repo) | ||
| 85 | |||
| 86 | See https://op.xwiki.org/projects | ||
| 87 | |||
| 88 | > REQM10: Be able to have several groups ([[categories in JIRA>>https://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=10000]] parlance) | ||
| 89 | |||
| 90 | Projects can be nested so the solution is to create a container project. | ||
| 91 | |||
| 92 | For example: | ||
| 93 | * [[Contrib Projects>>https://op.xwiki.org/projects/contrib-projects]] | ||
| 94 | * [[XS Projects>>https://op.xwiki.org/projects/xs-projects]] | ||
| 95 | |||
| 96 | > REQM11: Be able to mass refactor issues (select issues with a query and then apply changes to all of them: add a fix version, etc.) | ||
| 97 | |||
| 98 | There's the concept of [[Bulk Edit>>https://www.openproject.org/docs/user-guide/work-packages/edit-work-package/#bulk-edit-work-packages]]. | ||
| 99 | |||
| 100 | > REQM12: Be able to set permissions/groups/roles for authorization | ||
| 101 | |||
| 102 | See https://op.xwiki.org/users | ||
| 103 | |||
| 104 | > REQM13: Be publicly accessible | ||
| 105 | > REQM14: Be able to self-register and create issues | ||
| 106 | |||
| 107 | See https://op.xwiki.org/admin/settings/authentication?tab=registration | ||
| 108 | |||
| 109 | When a user self-registers, he/she is part of the "Non-Member" role by default. Thus we need to define the permissions of the "Non-Member" role to allow creation of work packages, etc. | ||
| 110 | |||
| 111 | > REQM15: Be able to have shared schemes to share configs between projects (permission scheme, workflow scheme, etc.) | ||
| 112 | |||
| 113 | Doesn't exist but there's the concept of Project Template. However, that's very painful as it's a copy and not a reference (i.e. if the template is modified then the existing projects created from that template are not updated). | ||
| 114 | |||
| 115 | This will lead to more maintenance and duplication. OTOH there are lots of features not available at the project level and which can thus only be configured at the global level (like workflows). For permissions for ex, we'll need to set it up for each project, using roles, to reduce maintenance. | ||
| 116 | |||
| 117 | > REQM16: Be able to define custom fields (we use that for documentation and flickering tests for example) | ||
| 118 | |||
| 119 | Generally possible, see https://op.xwiki.org/admin/settings/project_custom_fields | ||
| 120 | |||
| 121 | {{warning}} | ||
| 122 | However, to implement our custom Reference Documentation field, it's not possible to use the Link type since we can have more than 1 URLs and OP doesn't support having a list of URLs... | ||
| 123 | The only solution right now is to use a Long text (textarea) but it has some drawbacks: | ||
| 124 | * It's not possible to display it as a column in the Work Package lists (since it's a textarea) | ||
| 125 | * We cannot put a good regex for it (the best we can do is ##^https://|^N\/A$##) but that means that users can start the content with a URL and then type whatever they want, without it being stricly URLs | ||
| 126 | {{/warning}} | ||
| 127 | |||
| 128 | > REQM17: Be able to receive notifications (individual or to a notification list) | ||
| 129 | |||
| 130 | See https://www.openproject.org/docs/user-guide/notifications/ | ||
| 131 | |||
| 132 | > REQM18: Be able to import existing issues from the current issue tracker (e.g. JIRA) and not loose metadata ideally | ||
| 133 | |||
| 134 | {{warning}} | ||
| 135 | Very rudimentary ATM for [[JIRA import>>https://www.openproject.org/docs/installation-and-operations/jira-migration/]] but it seems the OP devs are working on a better JIRA import. | ||
| 136 | |||
| 137 | We have 4 solutions: | ||
| 138 | 1. Wait for the official JIRA importer to be ready | ||
| 139 | 1. Use the JIRA and OP REST APIs and write code | ||
| 140 | 1. Try out the [[OP JIRA importer>>https://github.com/dotnetfactory/openproject-jira-importer]] (but I doubt it'll do all that we need) | ||
| 141 | 1. Don't import from JIRA and only use OP for new projects. Keep the JIRA instance in read-only mode. At least until the official JIRA importer is ready and good enough | ||
| 142 | |||
| 143 | Solution 4 seems to be the only reasonable one since we have thousands of JIRA queries on xwiki.org (using JQL for a lot of them, that we cannot easily convert or it would take a lot of time to do so). | ||
| 144 | {{/warning}} | ||
| 145 | |||
| 146 | > REQM19: Be able to move issues (and not have to close and copy issues) | ||
| 147 | |||
| 148 | It's possible to move work packages between project and set some properties at the same time. See https://www.openproject.org/docs/user-guide/work-packages/duplicate-move-delete/ | ||
| 149 | |||
| 150 | > REQM20: Be able to link between issues (“depends on”, “is related to”, etc.) | ||
| 151 | |||
| 152 | Each work packages has a "Relations" tab with plenty of available type of relations. | ||
| 153 | |||
| 154 | TODO: Check if relations can be customized/configured (to remove some for example) | ||
| 155 | |||
| 156 | > REQM21: Be able to see the detailed history of the issue | ||
| 157 | |||
| 158 | Available in the "Activity" tab of each work package. | ||
| 159 | |||
| 160 | > REQM22: Be able to add attachments and display pictures/video integrations | ||
| 161 | |||
| 162 | Attachments can be added to work packages, and images can also be added in comments of work packages (in this case the images are not visible uner the File tab). Images can be added by upload, copy/paste or drag and drop. | ||
| 163 | |||
| 164 | {{warning}} | ||
| 165 | Attachments [[can be referenced from a WP comment>>https://www.openproject.org/docs/user-guide/wysiwyg/#links-to-openproject-resources]] but it's [[currently not working>>https://community.openproject.org/projects/openproject/work_packages/70173/activity]]. | ||
| 166 | {{/warning}} | ||
| 167 | |||
| 168 | > REQM23: Be able to have priorities, including a Blocker priority. | ||
| 169 | |||
| 170 | See https://op.xwiki.org/admin/settings/work_package_priorities | ||
| 171 | |||
| 172 | > REQM24: Be able to have statuses (open, in progress, closed) | ||
| 173 | |||
| 174 | See https://op.xwiki.org/statuses | ||
| 175 | |||
| 176 | > REQM25: Be able to self-register confidential issues (e.g. for security issues) | ||
| 177 | |||
| 178 | {{error}} | ||
| 179 | It's not possible. | ||
| 180 | |||
| 181 | It's not even possible to set permissions on a work package. A workaround would be to create a confidential sub project with proper permissions but it's a major pain to maintain as subprojects don't inherit everything from their parent projects, causing lots of manual maintenance (e.g. categories). | ||
| 182 | {{/error}} | ||
| 183 | |||
| 184 | > REQM26: Be able to have different fields for different projects (e.g. some projects don't have the notion of Version) | ||
| 185 | |||
| 186 | {{error}} | ||
| 187 | Doesn't seem possible. The field organization seem to apply to all projects (you can only configure them differently per work package type). | ||
| 188 | |||
| 189 | Could also be useful to have some internal project where we define the yearly roadmap and use the workload fields to estimate the capacity. I guess this could be achieved with a new type but then this type could also be chosen for other projects, which shouldn't be possible. | ||
| 190 | {{/error}} | ||
| 191 | |||
| 192 | == Nice to Have == | ||
| 193 | |||
| 194 | > REQN01: Be able to have dashboards for releases (e.g. JIRA Dashboard) | ||
| 195 | |||
| 196 | Not configurable. See for ex https://community.openproject.org/versions/1413 | ||
| 197 | |||
| 198 | > REQN02: Be able to see similar issues when creating new issues to avoid duplicating existing issues | ||
| 199 | |||
| 200 | Not found. | ||
| 201 | |||
| 202 | > REQN03: Be able to execute scripts inside the issue tracker to query issues and perform changes | ||
| 203 | |||
| 204 | Not found. There's an [[experimental CLI>>https://www.openproject.org/blog/passion-project-openproject-cli/]] but it cannot be used to execute scripts. | ||
| 205 | |||
| 206 | > REQN04: Be able to link issues with issues from an external bug tracker (Apache JIRA instance, etc.) | ||
| 207 | |||
| 208 | Not found. But could be implemented using a custom field (but it won't show the status dynamically). | ||
| 209 | |||
| 210 | > REQN05: Be able to sponsor issues (e.g. we used to use FreedomSponsors in the past) | ||
| 211 | |||
| 212 | Not found. | ||
| 213 | |||
| 214 | == Additional == | ||
| 215 | |||
| 216 | > Ability to list project attributes on the project home page. | ||
| 217 | |||
| 218 | We have defined the following attributes: | ||
| 219 | * Extension URL: Link to where the top-level extension for this project can be found on extensions.xwiki.org | ||
| 220 | * Lead: The lead of the project (for contrib projects) | ||
| 221 | |||
| 222 | For ex, see https://op.xwiki.org/projects/latex/ | ||
| 223 | |||
| 224 | > Be able to set several fix Versions | ||
| 225 | |||
| 226 | {{error}} | ||
| 227 | The built-in "Version" field only accepts a single value. There's a [[WP open to ask to make it multi-valued>>https://community.openproject.org/projects/openproject/work_packages/69904/activity]]. | ||
| 228 | |||
| 229 | Custom Version fields can be multi-valued but by doing so we would loose features such as the Roadmap UI which works only with the built-in "Version" field. There might be other features using the built-in "Version" field. | ||
| 230 | |||
| 231 | A workaround is to introduce a "Backport Versions" field but again it means that roadmaps will not be correct and the work packages with versions specified in the "Backport Versions" field won't appear in Release notes for these versions. | ||
| 232 | {{/error}} |
