Describe plugin related features in the Gerrit 2.5 release notes
Change-Id: Ia7400f854e5b8026017da210d8c5c13d132b87a0 Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
This commit is contained in:
Edwin Kempin
@@ -7,12 +7,14 @@ This page describes how plugins for Gerrit can be developed.
|
||||
Depending on how tightly the extension code is coupled with the Gerrit
|
||||
server code, there is a distinction between `plugins` and `extensions`.
|
||||
|
||||
[[plugin]]
|
||||
A `plugin` in Gerrit is tightly coupled code that runs in the same
|
||||
JVM as Gerrit. It has full access to all server internals. Plugins
|
||||
are tightly coupled to a specific major.minor server version and
|
||||
may require source code changes to compile against a different
|
||||
server version.
|
||||
|
||||
[[extension]]
|
||||
An `extension` in Gerrit runs inside of the same JVM as Gerrit
|
||||
in the same way as a plugin, but has limited visibility to the
|
||||
server's internals. The limited visibility reduces the extension's
|
||||
@@ -174,6 +176,7 @@ reload::
|
||||
To reload/restart a plugin the link:cmd-plugin-reload.html[plugin reload]
|
||||
command can be used.
|
||||
|
||||
[[classpath]]
|
||||
Classpath
|
||||
---------
|
||||
|
||||
@@ -189,6 +192,7 @@ link:http://maven.apache.org/plugins/maven-shade-plugin/[shade plugin]
|
||||
to package additional dependencies. Relocating (or renaming) classes
|
||||
should not be necessary due to the ClassLoader isolation.
|
||||
|
||||
[[ssh]]
|
||||
SSH Commands
|
||||
------------
|
||||
|
||||
@@ -243,6 +247,7 @@ by PrintHello class will be available to users as:
|
||||
$ ssh -p 29418 review.example.com helloworld print
|
||||
----
|
||||
|
||||
[[http]]
|
||||
HTTP Servlets
|
||||
-------------
|
||||
|
||||
@@ -291,6 +296,7 @@ by HelloServlet class will be available to users as:
|
||||
$ curl http://review.example.com/plugins/helloworld/print
|
||||
----
|
||||
|
||||
[[data-directory]]
|
||||
Data Directory
|
||||
--------------
|
||||
|
||||
@@ -307,6 +313,7 @@ Plugins can use this to store any data they want.
|
||||
}
|
||||
====
|
||||
|
||||
[[documentation]]
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
@@ -325,6 +332,7 @@ link:http://daringfireball.net/projects/markdown/[Markdown] style
|
||||
if the file name ends with `.md`. Gerrit will automatically convert
|
||||
Markdown to HTML if accessed with extension `.html`.
|
||||
|
||||
[[macros]]
|
||||
Within the Markdown documentation files macros can be used that allow
|
||||
to write documentation with reasonably accurate examples that adjust
|
||||
automatically based on the installation.
|
||||
@@ -346,6 +354,7 @@ from Markdown to HTML.
|
||||
Macros that start with `\` such as `\@KEEP@` will render as `@KEEP@`
|
||||
even if there is an expansion for `KEEP` in the future.
|
||||
|
||||
[[auto-index]]
|
||||
Automatic Index
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -386,6 +395,7 @@ displayed as part of the index page, if present in the manifest:
|
||||
|API Version | Gerrit-ApiVersion
|
||||
|===================================================
|
||||
|
||||
[[deployment]]
|
||||
Deployment
|
||||
----------
|
||||
|
||||
|
||||
@@ -104,6 +104,7 @@ Subprojects point to snapshot releases
|
||||
./tools/release.sh
|
||||
====
|
||||
|
||||
[[plugin-api]]
|
||||
Publish the Plugin API JAR File
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ link:http://code.google.com/p/gerrit/downloads/detail?name=gerrit-2.5.war[http:/
|
||||
Upgrade Warnings
|
||||
----------------
|
||||
|
||||
[[replication]]
|
||||
Replication
|
||||
~~~~~~~~~~~
|
||||
|
||||
@@ -53,3 +54,162 @@ stale the cached data can be. This is especially useful for slave
|
||||
servers account and permission data, or the `ldap_groups` cache, where
|
||||
updates are often made to the source without telling Gerrit to reload
|
||||
the cache.
|
||||
|
||||
New Features
|
||||
------------
|
||||
|
||||
Plugins
|
||||
~~~~~~~
|
||||
|
||||
The Gerrit server functionality can be extended by installing plugins.
|
||||
Depending on how tightly the extension code is coupled with the Gerrit
|
||||
server code, there is a distinction between
|
||||
link:../Documentation/dev-plugins.html#plugin[plugins] and
|
||||
link:../Documentation/dev-plugins.html#extension[extensions].
|
||||
|
||||
* link:#replication[Move replication logic to replication plugin]
|
||||
+
|
||||
This splits all of the replication code out of the core server
|
||||
and moves it into a standard plugin.
|
||||
|
||||
* link:../Documentation/dev-plugins.html[Documentation about
|
||||
plugin development] including instructions for:
|
||||
** link:../Documentation/dev-plugins.html#getting-started[how to get
|
||||
started with plugin development]
|
||||
** link:../Documentation/dev-plugins.html#deployment[plugin
|
||||
deployment/installation]
|
||||
|
||||
* link:../Documentation/dev-plugins.html#API[API for plugins and
|
||||
extensions]
|
||||
|
||||
* Support for link:../Documentation/dev-plugins.html#ssh[SSH command
|
||||
plugins]
|
||||
+
|
||||
Allows plugin developers to declare additional SSH commands.
|
||||
|
||||
* Enable aliases for SSH commands
|
||||
+
|
||||
Site administrators can alias SSH commands from a plugin into the
|
||||
`gerrit` namespace.
|
||||
+
|
||||
The aliases are configured statically at server startup, but are
|
||||
resolved dynamically at invocation time to the currently loaded
|
||||
version of the plugin. If the plugin is not loaded, or does not
|
||||
define the command, "not found" is returned to the user.
|
||||
|
||||
* Support for link:../Documentation/dev-plugins.html#http[HTTP
|
||||
plugins]
|
||||
+
|
||||
Plugins may contribute to the /plugins/NAME/ URL space.
|
||||
|
||||
* Automatic registration of plugin bindings
|
||||
+
|
||||
If a plugin has no modules declared in the manifest, automatically
|
||||
generate the modules for the plugin based on the class files that
|
||||
appear in the plugin and the `@Export` annotations that appear on
|
||||
these concrete classes.
|
||||
+
|
||||
For any non-abstract command that extends SshCommand, plugins may
|
||||
declare the command with `@Export("name")` to
|
||||
link:../Documentation/dev-plugins.html#ssh[bind the implementation
|
||||
as that SSH command].
|
||||
+
|
||||
Likewise link:../Documentation/dev-plugins.html#http[HTTP servlets
|
||||
can also be bound to URLs].
|
||||
|
||||
* link:../Documentation/dev-plugins.html#data-directory[Support a data
|
||||
directory for plugins on demand]
|
||||
|
||||
* Support serving static/ and Documentation/ from plugins
|
||||
+
|
||||
The static/ and Documentation/ resource directories of a plugin can be
|
||||
served over HTTP for any loaded and running plugin, even if it has no
|
||||
other HTTP handlers. This permits a plugin to supply icons or other
|
||||
graphics for the web UI, or documentation content to help users learn
|
||||
how to use the plugin.
|
||||
|
||||
* link:../Documentation/dev-plugins.html#documentation[Auto-formatting
|
||||
of plugin HTTP pages from Markdown files]
|
||||
+
|
||||
If Gerrit detects that a requested plugin resource does not exist, but
|
||||
instead a file with a `.md` extension does exist, Gerrit opens the
|
||||
`.md` file and reformats it as html.
|
||||
|
||||
* Support of link:../Documentation/dev-plugins.html#macros[macros in
|
||||
Markdown plugin documentation]
|
||||
|
||||
* link:../Documentation/dev-plugins.html#auto-index[Automatic
|
||||
generation of an index for the plugin documentation]
|
||||
|
||||
* Support for audit plugins
|
||||
+
|
||||
Plugins can implement an `AuditListener` to be informed about auditable
|
||||
actions:
|
||||
+
|
||||
----
|
||||
@Listener
|
||||
public class MyAuditTrail extends AuditListener
|
||||
----
|
||||
+
|
||||
The plugin must define a plugin module that binds the implementation of
|
||||
the audit listener in the `configure()` method:
|
||||
+
|
||||
----
|
||||
DynamicSet.bind(binder(), AuditListener.class).to(MyAuditTrail.class);
|
||||
----
|
||||
|
||||
* Web UI for plugins
|
||||
+
|
||||
Administrators can see the list of installed plugins in the WebUI
|
||||
under `Admin` > `Plugins`. For each plugin the plugin status is shown
|
||||
and it is possible to navigate to the plugin documentation.
|
||||
|
||||
* Servlet to list plugins
|
||||
+
|
||||
Administrators can retrieve plugin information from a REST interface
|
||||
by loading `<server-url>/a/plugins/`.
|
||||
|
||||
* Support SSH commands to
|
||||
** link:../Documentation/cmd-plugin-ls.html[list the installed
|
||||
plugins]
|
||||
** link:../Documentation/cmd-plugin-install.html[install plugins]
|
||||
** link:../Documentation/cmd-plugin-enable.html[enable plugins]
|
||||
** link:../Documentation/cmd-plugin-remove.html[disable plugins]
|
||||
** link:../Documentation/cmd-plugin-reload.html[reload plugins]
|
||||
|
||||
* Support installation of core plugin on site initialization
|
||||
|
||||
* Automatically load/unload/reload plugins
|
||||
+
|
||||
The PluginScanner thread runs every 1 minute by default and loads any
|
||||
newly created plugins, unloads any deleted plugins, and reloads any
|
||||
plugins that have been modified.
|
||||
+
|
||||
The check frequency can be configured by setting
|
||||
link:../Documentation/config-gerrit.html#plugins.checkFrequency[
|
||||
plugins.checkFrequency] in the Gerrit config file. By configuration
|
||||
the scanner can also be disabled.
|
||||
|
||||
* link:../Documentation/dev-plugins.html#classpath[Loading of plugins
|
||||
in own ClassLoader]
|
||||
|
||||
* Plugin cleanup in the background
|
||||
+
|
||||
When a plugin is stopped, schedule a Plugin Cleaner task to run
|
||||
1 minute later to try and clean out the garbage and release the
|
||||
JAR from `$site_path/tmp`.
|
||||
|
||||
* Export `LifecycleListener` as extension point
|
||||
+
|
||||
Extensions may need to know when they are starting or stopping.
|
||||
Export the interface that they can use to learn this information.
|
||||
|
||||
* Support injection of `ServerInformation` into extensions and plugins
|
||||
+
|
||||
Plugins can take this value by injection and learn the current
|
||||
server state during their own LifecycleListener. This enables a
|
||||
plugin to determine if it is loading as part of server startup, or
|
||||
because it was dynamically installed or reloaded by an administrator.
|
||||
|
||||
* link:../Documentation/dev-plugins.html#getting-started[Maven
|
||||
archetype for creating gerrit plugin projects]
|
||||
|
||||
Reference in New Issue
Block a user