blob: 04e2420dee82c1494c23cf14076dba871ae4ce3c [file] [log] [blame]
Marian Harbachebeb1542019-12-13 10:42:46 +01001:linkattrs:
Edwin Kempinef1b8112019-10-29 09:27:00 +01002= Gerrit Code Review - Core Plugins
3
4[[definition]]
5== What are core plugins?
6
7Core plugins are plugins that are packaged within the Gerrit war file. This
8means during the link:pgm-init.html[Gerrit initialization] they can be easily
9installed without downloading any additional files.
10
11To make working with core plugins easy, they are linked as
12link:https://gerrit.googlesource.com/gerrit/+/refs/heads/master/.gitmodules[Git
Marian Harbach34253372019-12-10 18:01:31 +010013submodules,role=external,window=_blank] in the `gerrit` repository. E.g. this means they can be easily
Edwin Kempinef1b8112019-10-29 09:27:00 +010014link:dev-readme.html#clone[cloned] together with Gerrit.
15
Edwin Kempin2e50db22019-10-28 15:09:14 +010016All core plugins are developed and maintained by the
17link:dev-roles.html#maintainers[Gerrit maintainers] and everyone can
18link:dev-contributing.html[contribute] to them.
19
20Adding a new core plugin feature that is large or complex requires a
21link:dev-design-doc.html[design doc] (also see
22link:dev-contributing.html#design-driven-contribution-process[design-driven
23contribution process]). The link:dev-processes.html#steering-committee[
24engineering steering committee (ESC)] is the authority that approves the design
25docs. The ESC is also in charge of adding and removing core plugins.
26
27Non-Gerrit maintainers cannot have link:access-control.html#category_owner[
28Owner] permissions for core plugins.
Edwin Kempinef1b8112019-10-29 09:27:00 +010029
Edwin Kempinca617aa2019-10-30 14:38:51 +010030[[list]]
31== Which core plugins exist?
32
33See link:config-plugins.html#core-plugins[here].
34
Edwin Kempin0e33c71d2019-10-28 15:57:46 +010035[[criteria]]
36=== Criteria for Core Plugins
37
38To be considered as a core plugin, a plugin must fulfill the following
39criteria:
40
411. License:
42+
43The plugin code is available under the
Marian Harbach34253372019-12-10 18:01:31 +010044link:http://www.apache.org/licenses/LICENSE-2.0[Apache License Version 2.0,role=external,window=_blank].
Edwin Kempin0e33c71d2019-10-28 15:57:46 +010045
462. Hosting:
47+
48The plugin development is hosted on the
Marian Harbach34253372019-12-10 18:01:31 +010049link:https://gerrit-review.googlesource.com[gerrit-review,role=external,window=_blank] Gerrit Server.
Edwin Kempin0e33c71d2019-10-28 15:57:46 +010050
513. Scope:
52+
53The plugin functionality is Gerrit-related, has a clear scope and does not
54conflict with other core plugins or existing and planned Gerrit core features.
55
564. Relevance:
57+
58The 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+
70Whether a plugin is relevant to a majority of the Gerrit community must be
71discussed on a case-by-case basis. In case of doubt, it's up to the
72link:dev-processes.html#steering-committee[engineering steering committee] to
73make a decision.
74
755. Code Quality:
76+
77The plugin code is mature and has a good test coverage. Maintaining the plugin
78code creates only little overhead for the Gerrit maintainers.
79
806. Documentation:
81+
82The plugin functionality is fully documented.
83
847. Ownership:
85+
86Existing plugin owners which are not Gerrit maintainers must agree to give up
87their ownership. If the current plugin owners disagree, forking the plugin is
88possible, but this should happen only in exceptional cases.
89
Edwin Kempinca617aa2019-10-30 14:38:51 +010090[[process-to-make-a-plugin-a-core-plugin]]
91== Process to make a plugin a core plugin
Edwin Kempinef1b8112019-10-29 09:27:00 +010092
Edwin Kempinca617aa2019-10-30 14:38:51 +010093Anyone can propose to make a plugin a core plugin, but to be accepted as core
94plugin the plugin must fulfill certain link:#criteria[criteria].
95
961. Propose a plugin as core plugin:
97+
98File a link:https://bugs.chromium.org/p/gerrit/issues/entry?template=Core+Plugin+Request[
99Core Plugin Request] in the issue tracker and provide the information that is
100being asked for in the request template.
101
1022. Community Feedback:
103+
104Anyone can comment on the issue to raise concerns or to support the request.
105The issue should stay open for at least 10 calendar days so that everyone in
106the community has a chance to comment.
107
1083. ESC Decision:
109+
110The ESC should discuss the request and reject/approve it or ask for further
111information that the reporter or commenters should provide.
112+
113Any decision must be based on the link:#criteria[criteria] that core plugins
114are expected to fulfill and should take the feedback from the community into
115account.
116+
117Accepting the request is only possible if the issue was open for at least 10
118calendar days (see 2., this gives the community time to comment).
119+
120When the ESC approves/rejects the request a summary of the reasons for the
121decision should be added to the issue.
122+
123If a request is rejected, it's possible to ask for a revalidation if the
124concerns that led to the rejection have been addressed (e.g. the plugin was
125rejected due to missing tests, but tests have been added afterwards).
126
1274. Add plugin as core plugin:
128+
129If the request was accepted, a Gerrit maintainer should add the plugin as
130core 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 Kempinef1b8112019-10-29 09:27:00 +0100157
158GERRIT
159------
160Part of link:index.html[Gerrit Code Review]
161
162SEARCHBOX
163---------