Marian Harbach | ebeb154 | 2019-12-13 10:42:46 +0100 | [diff] [blame] | 1 | :linkattrs: |
Edwin Kempin | ef1b811 | 2019-10-29 09:27:00 +0100 | [diff] [blame] | 2 | = Gerrit Code Review - Core Plugins |
| 3 | |
| 4 | [[definition]] |
| 5 | == What are core plugins? |
| 6 | |
| 7 | Core plugins are plugins that are packaged within the Gerrit war file. This |
| 8 | means during the link:pgm-init.html[Gerrit initialization] they can be easily |
| 9 | installed without downloading any additional files. |
| 10 | |
| 11 | To make working with core plugins easy, they are linked as |
| 12 | link:https://gerrit.googlesource.com/gerrit/+/refs/heads/master/.gitmodules[Git |
Marian Harbach | 3425337 | 2019-12-10 18:01:31 +0100 | [diff] [blame] | 13 | submodules,role=external,window=_blank] in the `gerrit` repository. E.g. this means they can be easily |
Edwin Kempin | ef1b811 | 2019-10-29 09:27:00 +0100 | [diff] [blame] | 14 | link:dev-readme.html#clone[cloned] together with Gerrit. |
| 15 | |
Edwin Kempin | 2e50db2 | 2019-10-28 15:09:14 +0100 | [diff] [blame] | 16 | All core plugins are developed and maintained by the |
| 17 | link:dev-roles.html#maintainers[Gerrit maintainers] and everyone can |
| 18 | link:dev-contributing.html[contribute] to them. |
| 19 | |
| 20 | Adding a new core plugin feature that is large or complex requires a |
| 21 | link:dev-design-doc.html[design doc] (also see |
| 22 | link:dev-contributing.html#design-driven-contribution-process[design-driven |
| 23 | contribution process]). The link:dev-processes.html#steering-committee[ |
| 24 | engineering steering committee (ESC)] is the authority that approves the design |
| 25 | docs. The ESC is also in charge of adding and removing core plugins. |
| 26 | |
| 27 | Non-Gerrit maintainers cannot have link:access-control.html#category_owner[ |
| 28 | Owner] permissions for core plugins. |
Edwin Kempin | ef1b811 | 2019-10-29 09:27:00 +0100 | [diff] [blame] | 29 | |
Edwin Kempin | ca617aa | 2019-10-30 14:38:51 +0100 | [diff] [blame] | 30 | [[list]] |
| 31 | == Which core plugins exist? |
| 32 | |
| 33 | See link:config-plugins.html#core-plugins[here]. |
| 34 | |
Edwin Kempin | 0e33c71d | 2019-10-28 15:57:46 +0100 | [diff] [blame] | 35 | [[criteria]] |
| 36 | === Criteria for Core Plugins |
| 37 | |
| 38 | To be considered as a core plugin, a plugin must fulfill the following |
| 39 | criteria: |
| 40 | |
| 41 | 1. License: |
| 42 | + |
| 43 | The plugin code is available under the |
Marian Harbach | 3425337 | 2019-12-10 18:01:31 +0100 | [diff] [blame] | 44 | link:http://www.apache.org/licenses/LICENSE-2.0[Apache License Version 2.0,role=external,window=_blank]. |
Edwin Kempin | 0e33c71d | 2019-10-28 15:57:46 +0100 | [diff] [blame] | 45 | |
| 46 | 2. Hosting: |
| 47 | + |
| 48 | The plugin development is hosted on the |
Marian Harbach | 3425337 | 2019-12-10 18:01:31 +0100 | [diff] [blame] | 49 | link:https://gerrit-review.googlesource.com[gerrit-review,role=external,window=_blank] Gerrit Server. |
Edwin Kempin | 0e33c71d | 2019-10-28 15:57:46 +0100 | [diff] [blame] | 50 | |
| 51 | 3. Scope: |
| 52 | + |
| 53 | The plugin functionality is Gerrit-related, has a clear scope and does not |
| 54 | conflict with other core plugins or existing and planned Gerrit core features. |
| 55 | |
| 56 | 4. Relevance: |
| 57 | + |
| 58 | The plugin functionality is relevant to a majority of the Gerrit community: |
| 59 | + |
| 60 | -- |
| 61 | ** An out of the box Gerrit installation would seem like it is missing |
| 62 | something if the plugin is not installed. |
| 63 | ** It's expected that most sites would use the plugin. |
| 64 | ** Multiple parties (different organizations/companies) already use the plugin |
| 65 | and agree that it should be offered as core plugin. |
| 66 | ** If the same or similar functionality is provided by multiple plugins, |
| 67 | the plugin is the clear recommended solution by the community. |
| 68 | -- |
| 69 | + |
| 70 | Whether a plugin is relevant to a majority of the Gerrit community must be |
| 71 | discussed on a case-by-case basis. In case of doubt, it's up to the |
| 72 | link:dev-processes.html#steering-committee[engineering steering committee] to |
| 73 | make a decision. |
| 74 | |
| 75 | 5. Code Quality: |
| 76 | + |
| 77 | The plugin code is mature and has a good test coverage. Maintaining the plugin |
| 78 | code creates only little overhead for the Gerrit maintainers. |
| 79 | |
| 80 | 6. Documentation: |
| 81 | + |
| 82 | The plugin functionality is fully documented. |
| 83 | |
| 84 | 7. Ownership: |
| 85 | + |
| 86 | Existing plugin owners which are not Gerrit maintainers must agree to give up |
| 87 | their ownership. If the current plugin owners disagree, forking the plugin is |
| 88 | possible, but this should happen only in exceptional cases. |
| 89 | |
Edwin Kempin | ca617aa | 2019-10-30 14:38:51 +0100 | [diff] [blame] | 90 | [[process-to-make-a-plugin-a-core-plugin]] |
| 91 | == Process to make a plugin a core plugin |
Edwin Kempin | ef1b811 | 2019-10-29 09:27:00 +0100 | [diff] [blame] | 92 | |
Edwin Kempin | ca617aa | 2019-10-30 14:38:51 +0100 | [diff] [blame] | 93 | Anyone can propose to make a plugin a core plugin, but to be accepted as core |
| 94 | plugin the plugin must fulfill certain link:#criteria[criteria]. |
| 95 | |
| 96 | 1. Propose a plugin as core plugin: |
| 97 | + |
| 98 | File a link:https://bugs.chromium.org/p/gerrit/issues/entry?template=Core+Plugin+Request[ |
| 99 | Core Plugin Request] in the issue tracker and provide the information that is |
| 100 | being asked for in the request template. |
| 101 | |
| 102 | 2. Community Feedback: |
| 103 | + |
| 104 | Anyone can comment on the issue to raise concerns or to support the request. |
| 105 | The issue should stay open for at least 10 calendar days so that everyone in |
| 106 | the community has a chance to comment. |
| 107 | |
| 108 | 3. ESC Decision: |
| 109 | + |
| 110 | The ESC should discuss the request and reject/approve it or ask for further |
| 111 | information that the reporter or commenters should provide. |
| 112 | + |
| 113 | Any decision must be based on the link:#criteria[criteria] that core plugins |
| 114 | are expected to fulfill and should take the feedback from the community into |
| 115 | account. |
| 116 | + |
| 117 | Accepting the request is only possible if the issue was open for at least 10 |
| 118 | calendar days (see 2., this gives the community time to comment). |
| 119 | + |
| 120 | When the ESC approves/rejects the request a summary of the reasons for the |
| 121 | decision should be added to the issue. |
| 122 | + |
| 123 | If a request is rejected, it's possible to ask for a revalidation if the |
| 124 | concerns that led to the rejection have been addressed (e.g. the plugin was |
| 125 | rejected due to missing tests, but tests have been added afterwards). |
| 126 | |
| 127 | 4. Add plugin as core plugin: |
| 128 | + |
| 129 | If the request was accepted, a Gerrit maintainer should add the plugin as |
| 130 | core plugin: |
| 131 | + |
| 132 | -- |
| 133 | ** Host the plugin repo on link:https://gerrit-review.googlesource.com/[ |
| 134 | gerrit-review]. |
| 135 | ** Ensure that the plugin repo inherits from the |
| 136 | link:https://gerrit-review.googlesource.com/admin/repos/Public-Plugins[ |
| 137 | Public-Plugins] repo. |
| 138 | ** Remove all permissions on the plugin repo (the inherited permissions from |
| 139 | `Public-Plugins` should be enough). Especially make sure that there are no |
| 140 | link:access-control.html#category_owner[Owner], |
| 141 | link:access-control.html#category_push_direct[Direct Push], |
| 142 | link:access-control.html#category_submit[Submit] or |
| 143 | link:access-control.html#category_review_labels[Code-Review+2] |
| 144 | permissions for non-Gerrit maintainers. |
| 145 | ** Create a component for the plugin in |
| 146 | link:https://bugs.chromium.org/p/gerrit/adminComponents[Monorail] and assign |
| 147 | all issues that already exist for the plugin to this component. |
| 148 | ** Add the plugin as |
| 149 | link:https://gerrit.googlesource.com/gerrit/+/refs/heads/master/.gitmodules[Git |
| 150 | submodule]. |
| 151 | ** Register the plugin as core plugin in |
| 152 | link:https://gerrit.googlesource.com/gerrit/+/refs/heads/master/tools/bzl/plugins.bzl[ |
| 153 | plugins.bzl]. |
| 154 | ** Announce the new core plugin in the |
| 155 | link:https://www.gerritcodereview.com/news.html[project news]. |
| 156 | -- |
Edwin Kempin | ef1b811 | 2019-10-29 09:27:00 +0100 | [diff] [blame] | 157 | |
| 158 | GERRIT |
| 159 | ------ |
| 160 | Part of link:index.html[Gerrit Code Review] |
| 161 | |
| 162 | SEARCHBOX |
| 163 | --------- |