Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.api.IRepositoryChangeListener

Timestamp:

Jul 20, 2014, 12:06:19 AM (10 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.api.IRepositoryChangeListener

@@ +1 @@
+== Extension Point : ''IRepositoryChangeListener'' ==
+
+||'''Interface'''||''IRepositoryChangeListener''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IRepositoryChangeListener 0.12]||
+||'''Module'''||''trac.versioncontrol.api''||'''Source'''||[source:trunk/trac/versioncontrol/api.py#/IRepositoryChangeListener api.py]||
+
+The ''IRepositoryChangeListener'' allows components to listen for and to react to changes in repositories.
+
+== Purpose ==
+
+Trac can be connected to Version Control systems to e.g. [TracBrowser browse files], [TracChangeset visualize changesets] or [TracRevisionLog revision logs]. Plugins can hook into the version control module to trigger their own actions when changesets are added or modified.
+
+The main purpose for this interface is to allow plugins to react to commits and trigger appropriate actions elsewhere (e.g. sending notifications or triggering changes via commands in the commit log messages etc.)
+
+For example the CommitTicketUpdater allows referencing or closing tickets by embedding the ticket number in a commit log message.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+The method `changeset_added` is called once for each new changeset committed to the repository.
+
+For repositories that allow revision property changes (SVN), the method `changeset_modified` is called once for each changeset modified.
+
+Note that the methods will not be called if the TracRepositoryAdmin is not configured correctly to call `trac-admin $ENV changeset added/modified` from the source control hooks.
+
+== Examples ==
+
+Similarly to the CommitTicketUpdater  mentioned above, you might want [ticket:9263 to close a milestone from a commit log message], e.g. when committing a tag or merging a branch.
+The following minimal example IWikiChangeListener implementation could implement such a feature:
+{{{#!python
+from datetime import datetime
+import re
+from trac.core import Component, implements
+from trac.ticket.model import Milestone
+from trac.util.datefmt import utc
+from trac.versioncontrol.api import IRepositoryChangeListener
+
+class CommitMilestoneCloser(Component):
+    implements(IRepositoryChangeListener)
+
+    def changeset_added(self, repos, changeset):
+        ref = re.search('complete milestone ([^\s]+)', changeset.message)
+        if ref:
+            milestone = Milestone(self.env, ref.group(1))
+            milestone.completed = datetime.now(utc)
+            milestone.update()
+
+    def changeset_modified(self, repos, changeset, old_changeset):
+        pass
+}}}
+
+== Available Implementations ==
+
+* CommitTicketUpdater
+
+* th:FullTextSearchPlugin: Updates search index.
+* th:MultiProjectCommitTicketUpdaterPlugin: Variation of CommitTicketUpdater that requires project prefixes.
+* th:TracTicketChangesetsPlugin: Maintains a DB table that lists changesets referencing a ticket.
+* th:CodeReviewerPlugin: Maintains a DB table that maps changesets to referenced tickets for code reviewing purposes.
+
+== Additional Information and References ==
+
+ * [apiref:trac.versioncontrol.api.IRepositoryChangeListener-class epydoc]
+ * [apidoc:api/trac_versioncontrol_api#trac.versioncontrol.api.IRepositoryChangeListener API Reference]
+  * See [../trac.ticket.api.IMilestoneChangeListener trac.ticket.api.IMilestoneChangeListener], [../trac.ticket.api.ITicketChangeListener trac.ticket.api.ITicketChangeListener], [../trac.wiki.api.IWikiChangeListener trac.wiki.api.IWikiChangeListener],  [../trac.attachment.IAttachmentChangeListener trac.attachment.IAttachmentChangeListener]
+ * [TracDev/DatabaseSchema/VersionControl Version control cache database schema]
+ * Related tickets:
+   * Generic change listener replacement: #8834, #11148, #6543, Trac-dev:7737
+   * #9263: Requested an implementation of a `CommitMilestoneUpdater`.
+   * #8732: Requested an implementation of a `CommitHoursUpdater` for time tracking.
+   * #731: Requested an implementation of  a `CommitNotificationSender`.
+
+=== API History
+ * [wiki:TracDev/ApiChanges/0.12#IRepositoryChangeListener 0.12] introduced the interface (#7723, changeset:7961)