Documentation/dev-plugins-lifecycle.txt

:linkattrs:
= Plugin Lifecycle

Most of the plugins are hosted on the same instance as the
link:https://gerrit-review.googlesource.com[Gerrit project itself,role=external,window=_blank] to make them
more discoverable and have more chances to be reviewed by the whole community.

[[hosting_lifecycle]]
== Hosting Lifecycle

The process of writing a new plugin goes through different phases:

- Ideation and Discussion:
+
The idea of creating a new plugin is posted and discussed on the
link:https://groups.google.com/d/forum/repo-discuss[repo-discuss,role=external,window=_blank] mailing list.
+
Also see section <<ideation_discussion>> below.

- Prototyping (optional):
+
The author of the plugin creates a working prototype on a public repository
accessible to the community.
+
Also see section <<plugin_prototyping>> below.

- Proposal and Hosting:
+
The author proposes to release the plugin under the
link:https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 OpenSource
license,role=external,window=_blank] and requests the plugin to be hosted on
link:https://gerrit-review.googlesource.com[the Gerrit project site,role=external,window=_blank]. The
proposal must be   accepted by at least one Gerrit maintainer. In case of
disagreement between maintainers, the issue can be escalated to the
link:dev-processes.html#steering-committee[Engineering Steering Committee]. If
the plugin is accepted, the Gerrit maintainer creates the project under the
plugins path on link:https://gerrit-review.googlesource.com[the Gerrit project
site,role=external,window=_blank].
+
Also see section <<plugin_proposal>> below.

- Build:
+
To make the consumption of the plugin easy and to notice plugin breakages early
the plugin author should setup build jobs on
link:https://gerrit-ci.gerritforge.com[the GerritForge CI,role=external,window=_blank] that build the
plugin for each Gerrit version that it supports.
+
Also see section <<build>> below.

- Development and Contribution:
+
The author develops a production-ready code base of the plugin, with
contributions, reviews, and help from the Gerrit community.
+
Also see section <<development_contribution>>
below.

- Release:
+
The author releases the plugin by creating a Git tag and announcing the plugin
on the link:https://groups.google.com/d/forum/repo-discuss[repo-discuss,role=external,window=_blank]
mailing list.
+
Also see section <<plugin_release>> below.

- Maintenance:
+
The author maintains their plugins as new Gerrit versions are released, updates
them when necessary, develops further existing or new features and reviews
incoming contributions.

- Deprecation:
+
The author declares that the plugin is not maintained anymore or is deprecated
and should not be used anymore.
+
Also see section <<plugin_deprecation>> below.

[[ideation_discussion]]
== Ideation and Discussion

Starting a new plugin project is a community effort: it starts with the
identification of a gap in the Gerrit Code Review product but evolves with the
contribution of ideas and suggestions by the whole community.

The ideator of the plugin starts with an RFC (Request For Comments) post on the
link:https://groups.google.com/d/forum/repo-discuss[repo-discuss,role=external,window=_blank] mailing list
with a description of the main reasons for starting a new plugin.

Example of a post:

----
  [RFC] Code-Formatter plugin

  Hello, community,
  I am proposing to create a new plugin for Gerrit called 'Code-Formatter', see
  the details below.

  *The gap*
  Often, when I post a new change to Gerrit, I forget to run the common code
  formatting tool (e.g. Google-Java-Format for the Gerrit project). I would
  like Gerrit to be in charge of highlighting these issues to me and save many
  people's time.

  *The proposal*
  The Code-Formatter plugin reads the formatting rules in the project config
  and applies them automatically to every patch-set. Any issue is reported as a
  regular review comment to the patchset, highlighting the part of the code to
  be changed.

  What do you think? Did anyone have the same idea or need?
----

The idea is discussed on the mailing list and can evolve based on the needs and
inputs from the entire community.

After the discussion, the ideator of the plugin can decide to start prototyping
on it or park the proposal, if the feedback provided an alternative solution to
the problem. The prototype phase can be optionally skipped if the idea is clear
enough and receives a general agreement from the Gerrit maintainers. The author
can be given a "leap of faith" and can go directly to the format plugin
proposal (see below) and the creation of the plugin repository.

[[plugin_prototyping]]
== Plugin Prototyping

The initial idea is translated to code by the plugin author. The development
can happen on any public or private source code repository and can involve one
or more contributors. The purpose of prototyping is to verify that the idea can
be implemented and provides the expected benefits.

Once a working prototype is ready, it can be announced as a follow-up to the
initial RFC proposal so that other members of the community can see the code
and try the plugin themselves.

[[plugin_proposal]]
== Plugin Proposal

The author decides that the plugin prototype makes sense as a general purpose
plugin and decides to release the code with the same
link:https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license,role=external,window=_blank]
as the Gerrit Code Review project and have it hosted on
link:https://gerrit-review.googlesource.com[the Gerrit project site,role=external,window=_blank].

The plugin author formalizes the proposal with a follow-up of the initial RFC
post and asks for public opinion on it.

Example:

----
  Re - [RFC] Code-Formatter plugin

  Hello, community,
  thanks for your feedback on the prototype. I have now decided to donate the
  project to the Gerrit Code Review project and make it a plugin:

  Plugin name:
  /plugins/code-formatter

  Plugin description:
    Plugin to allow automatic posting review based on code-formatting rules
----

The community discusses the proposal and the value of the plugin for the whole
project; the result of the discussion can end up in one of the following cases:

- The plugin's project request is widely appreciated and formally accepted by
  at least one Gerrit maintainer who creates the repository as child project of
  'Public-Projects' on link:https://gerrit-review.googlesource.com[the Gerrit
  project site,role=external,window=_blank], creates an associated plugin owners group with "Owner"
  permissions for the plugin and adds the plugin's author as member of it.
- The plugin's project is widely appreciated; however, another existing plugin
  already partially covers the same use-case and thus it would make more sense
  to have the features integrated into the existing plugin. The new plugin's
  author contributes his prototype commits refactored to be included as change
  into the existing plugin.
- The plugin's project is found useful; however, it is too specific to the
  author's use-case and would not make sense outside of it. The plugin remains
  in a public repository, widely accessible and OpenSource, but not hosted on
  link:https://gerrit-review.googlesource.com[the Gerrit project site,role=external,window=_blank].

[[build]]
== Build

The plugin's maintainer creates a job on the
link:https://gerrit-ci.gerritforge.com[GerritForge CI,role=external,window=_blank] by creating a new YAML
definition in the link:https://gerrit.googlesource.com/gerrit-ci-scripts[Gerrit
CI Scripts,role=external,window=_blank] repository.

Example of a YAML CI job for plugins:

----
  - project:
    name: code-formatter
    jobs:
      - 'plugin-{name}-bazel-{branch}':
          branch:
            - master
----

[[development_contribution]]
== Development and Contribution

The plugin follows the same lifecycle as Gerrit Code Review and needs to be
kept up-to-date with the current active branches, according to the
link:https://www.gerritcodereview.com/#support[current support policy,role=external,window=_blank].
During the development, the plugin's maintainer can reward contributors
requesting to be more involved and making them maintainers of his plugin,
adding them to the list of the project owners.

[[branching_strategy]]
== Branching Strategy

Plugin maintainers are encouraged to adopt a minimal-branching approach that
balances compatibility across Gerrit core versions with sustainable maintenance
overhead.

[[development_branch_strategy]]
=== Development Branch Strategy

The plugin `master` branch is the primary development branch when no stable
branches exist. The goal is to keep `master` compatible with the current
Gerrit core release for as long as possible, avoiding premature branch
proliferation.

When stable branches exist, new features should be developed on the oldest
supported stable branch that can support them, then merged forward through
any intermediate stable branches and finally into `master`. This ensures the
feature is immediately available to users on older Gerrit versions without
requiring a separate backport.

[[reactive_branching]]
=== Just-in-Time Branching

Plugin branches are created reactively, not proactively. There is no
requirement to create a plugin branch for every Gerrit core release.

The decision flow is:

. Develop on plugin `master`.
. Test plugin `master` against the target Gerrit core version.
. If it builds and works → continue using `master`; no new branch is needed.
. If it breaks:
  .. Identify the last commit on `master` that was compatible.
  .. Create a stable branch from that commit.
  .. Continue development for the new Gerrit core version on `master`.

A single plugin branch may remain compatible with multiple consecutive Gerrit
core versions. Branches should only diverge when API or behavioral
incompatibilities make it unavoidable.

[[core_version_relationship]]
=== Relationship to Gerrit Core Versions

There is no required one-to-one mapping between plugin branches and Gerrit
core versions. A single plugin branch can cover multiple Gerrit releases as
long as no incompatible API changes are introduced. Creating a dedicated branch
for every Gerrit release is discouraged, as it increases backport complexity
and maintenance overhead.

[[ci_limitations]]
=== CI Limitations and Expectations

Plugins are not continuously built against multiple Gerrit core versions
simultaneously. CI coverage does not guarantee early detection of
incompatibilities between a plugin and a given Gerrit core version. Some
breakages may only surface at runtime. This is an accepted trade-off given the
overhead of maintaining full multi-version CI pipelines.

[[plugin_release]]
== Plugin Release

The plugin's maintainer is the only person responsible for making and
announcing the official releases, typically, but not limited to, in conjunction
with the major releases of Gerrit Code Review. The plugin's maintainer may tag
his plugin and follow the notation and semantics of the Gerrit Code Review
project; however it is not mandatory and many of the plugins do not have any
tags or releases.

Example of a YAML CI job for a plugin compatible with multiple Gerrit versions:

----
  - project:
    name: code-formatter
    jobs:
      - 'plugin-{name}-bazel-{branch}-{gerrit-branch}':
          branch:
            - master
          gerrit-branch:
            - master
            - stable-3.0
            - stable-2.16
----

[[plugin_deprecation]]
== Plugin Deprecation

The plugin's maintainer and the community have agreed that the plugin is not
useful anymore or there isn't anyone willing to contribute to bringing it
forward and keeping it up-to-date with the recent versions of Gerrit Code
Review.

The plugin's maintainer puts a deprecation notice in the README.md of the
plugin and pushes it for review. If nobody is willing to bring the code
forward, the change gets merged, and the master branch is removed from the list
of branches to be built on the GerritForge CI.

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------