666aa8fd4b
When a user edits the commit message through the Gerrit web UI, send a notification email. Change-Id: I6f2d840f362d82af25960fb4f1891eee040de9a6
210 lines
6.2 KiB
Plaintext
210 lines
6.2 KiB
Plaintext
Gerrit Code Review - Mail Templates
|
|
===================================
|
|
|
|
Gerrit uses velocity templates for the bulk of the standard mails it sends out.
|
|
There are builtin default templates which are used if they are not overridden.
|
|
These defaults are also provided as examples so that administrators may copy
|
|
them and easily modify them to tweak their contents.
|
|
|
|
|
|
Template Locations and Extensions:
|
|
----------------------------------
|
|
|
|
The default example templates reside under: `'$site_path'/etc/mail` and are
|
|
terminated with the double extension `.vm.example`. Modifying these example
|
|
files will have no effect on the behavior of Gerrit. However, copying an
|
|
example template to an equivalently named file without the `.example` extension
|
|
and modifying it will allow an administrator to customize the template.
|
|
|
|
|
|
Supported Mail Templates:
|
|
-------------------------
|
|
|
|
Each mail that Gerrit sends out is controlled by at least one template. These
|
|
are listed below. Change emails are influenced by two additional templates,
|
|
one to set the subject line, and one to set the footer which gets appended to
|
|
all the change emails (see `ChangeSubject.vm` and `ChangeFooter.vm` below.)
|
|
|
|
Abandoned.vm
|
|
~~~~~~~~~~~~
|
|
|
|
The `Abandoned.vm` template will determine the contents of the email related
|
|
to a change being abandoned. It is a `ChangeEmail`: see `ChangeSubject.vm` and
|
|
`ChangeFooter.vm`.
|
|
|
|
ChangeFooter.vm
|
|
~~~~~~~~~~~~~~~
|
|
|
|
The `ChangeFooter.vm` template will determine the contents of the footer
|
|
text that will be appended to emails related to changes (all `ChangeEmail`s).
|
|
|
|
ChangeSubject.vm
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
The `ChangeSubject.vm` template will determine the contents of the email
|
|
subject line for ALL emails related to changes.
|
|
|
|
Comment.vm
|
|
~~~~~~~~~~
|
|
|
|
The `Comment.vm` template will determine the contents of the email related to
|
|
a user submitting comments on changes. It is a `ChangeEmail`: see
|
|
`ChangeSubject.vm`, `ChangeFooter.vm` and `CommentFooter.vm`.
|
|
|
|
CommentFooter.vm
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
The `CommentFooter.vm` template will determine the contents of the footer
|
|
text that will be appended to emails related to a user submitting comments on
|
|
changes. See `ChangeSubject.vm`, `Comment.vm` and `ChangeFooter.vm`.
|
|
|
|
CommitMessageEdited.vm
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The `CommitMessageEdited.vm` template will determine the contents of the email
|
|
related to a user editing the commit message through the Gerrit UI. It is a
|
|
`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
|
|
|
|
Merged.vm
|
|
~~~~~~~~~
|
|
|
|
The `Merged.vm` template will determine the contents of the email related to
|
|
a change successfully merged to the head. It is a `ChangeEmail`: see
|
|
`ChangeSubject.vm` and `ChangeFooter.vm`.
|
|
|
|
MergeFail.vm
|
|
~~~~~~~~~~~~
|
|
|
|
The `MergeFail.vm` template will determine the contents of the email related
|
|
to a failure upon attempting to merge a change to the head. It is a
|
|
`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
|
|
|
|
NewChange.vm
|
|
~~~~~~~~~~~~
|
|
|
|
The `NewChange.vm` template will determine the contents of the email related
|
|
to a user submitting a new change for review. It is a `ChangeEmail`: see
|
|
`ChangeSubject.vm` and `ChangeFooter.vm`.
|
|
|
|
RebasedPatchSet.vm
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The `RebasedPatchSet.vm` template will determine the contents of the email
|
|
related to a user rebasing a patchset for a change through the Gerrit UI.
|
|
It is a `ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
|
|
|
|
RegisterNewEmail.vm
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
The `RegisterNewEmail.vm` template will determine the contents of the email
|
|
related to registering new email accounts.
|
|
|
|
ReplacePatchSet.vm
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The `ReplacePatchSet.vm` template will determine the contents of the email
|
|
related to a user submitting a new patchset for a change. It is a
|
|
`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
|
|
|
|
Restored.vm
|
|
~~~~~~~~~~~
|
|
|
|
The `Restored.vm` template will determine the contents of the email related
|
|
to a change being restored. It is a `ChangeEmail`: see `ChangeSubject.vm` and
|
|
`ChangeFooter.vm`.
|
|
|
|
Reverted.vm
|
|
~~~~~~~~~~~
|
|
|
|
The `Reverted.vm` template will determine the contents of the email related
|
|
to a change being reverted. It is a `ChangeEmail`: see `ChangeSubject.vm` and
|
|
`ChangeFooter.vm`.
|
|
|
|
|
|
Mail Variables and Methods
|
|
--------------------------
|
|
|
|
Mail templates can access and display objects currently made available to them
|
|
via the velocity context. While the base objects are documented here, it is
|
|
possible to call public methods on these objects from templates. Those methods
|
|
are not documented here since they could change with every release. As these
|
|
templates are meant to be modified only by a qualified sysadmin, it is accepted
|
|
that writing templates for Gerrit emails is likely to require some basic
|
|
knowledge of the class structure to be useful. Browsing the source code might
|
|
be necessary for anything more than a minor formatting change.
|
|
|
|
Warning
|
|
~~~~~~~
|
|
|
|
Be aware that modifying templates can cause them to fail to parse and therefore
|
|
not send out the actual email, or worse, calling methods on the available
|
|
objects could have internal side effects which would adversely affect the
|
|
health of your Gerrit server and/or data.
|
|
|
|
All OutgoingEmails
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
All outgoing emails have the following variables available to them:
|
|
|
|
$email::
|
|
+
|
|
A reference to the class constructing the current `OutgoingEmail`. With this
|
|
reference it is possible to call any public method on the OutgoingEmail class
|
|
or the current child class inherited from it.
|
|
|
|
$messageClass::
|
|
+
|
|
A String containing the messageClass.
|
|
|
|
$StringUtils::
|
|
+
|
|
A reference to the Apache `StringUtils` class. This can be very useful for
|
|
formatting strings.
|
|
|
|
Change Emails
|
|
~~~~~~~~~~~~~
|
|
|
|
All change related emails have the following additional variables available to them:
|
|
|
|
$change::
|
|
+
|
|
A reference to the current `Change` object.
|
|
|
|
$changeId::
|
|
+
|
|
Id of the current change (a `Change.Key`).
|
|
|
|
$coverLetter::
|
|
+
|
|
The text of the `ChangeMessage`.
|
|
|
|
$branch::
|
|
+
|
|
A reference to the branch of this change (a `Branch.NameKey`).
|
|
|
|
$fromName::
|
|
+
|
|
The name of the from user.
|
|
|
|
$projectName::
|
|
+
|
|
The name of this change's project.
|
|
|
|
$patchSet::
|
|
+
|
|
A reference to the current `PatchSet`.
|
|
|
|
$patchSetInfo::
|
|
+
|
|
A reference to the current `PatchSetInfo`.
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
* link:http://velocity.apache.org/[velocity]
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|