Edgewall Software

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

Jul 20, 2014, 12:06:19 AM (8 years ago)
Peter Suter


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

    v1 v1  
     1== Extension Point : ''IRepositoryChangeListener'' ==
     3||'''Interface'''||''IRepositoryChangeListener''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IRepositoryChangeListener 0.12]||
     4||'''Module'''||''trac.versioncontrol.api''||'''Source'''||[source:trunk/trac/versioncontrol/api.py#/IRepositoryChangeListener api.py]||
     6The ''IRepositoryChangeListener'' allows components to listen for and to react to changes in repositories.
     8== Purpose ==
     10Trac 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.
     12The 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.)
     14For example the CommitTicketUpdater allows referencing or closing tickets by embedding the ticket number in a commit log message.
     16== Usage ==
     18Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     20The method `changeset_added` is called once for each new changeset committed to the repository.
     22For repositories that allow revision property changes (SVN), the method `changeset_modified` is called once for each changeset modified.
     24Note 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.
     26== Examples ==
     28Similarly 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.
     29The following minimal example IWikiChangeListener implementation could implement such a feature:
     31from datetime import datetime
     32import re
     33from trac.core import Component, implements
     34from trac.ticket.model import Milestone
     35from trac.util.datefmt import utc
     36from trac.versioncontrol.api import IRepositoryChangeListener
     38class CommitMilestoneCloser(Component):
     39    implements(IRepositoryChangeListener)
     41    def changeset_added(self, repos, changeset):
     42        ref = re.search('complete milestone ([^\s]+)', changeset.message)
     43        if ref:
     44            milestone = Milestone(self.env, ref.group(1))
     45            milestone.completed = datetime.now(utc)
     46            milestone.update()
     48    def changeset_modified(self, repos, changeset, old_changeset):
     49        pass
     52== Available Implementations ==
     54* CommitTicketUpdater
     56* th:FullTextSearchPlugin: Updates search index.
     57* th:MultiProjectCommitTicketUpdaterPlugin: Variation of CommitTicketUpdater that requires project prefixes.
     58* th:TracTicketChangesetsPlugin: Maintains a DB table that lists changesets referencing a ticket.
     59* th:CodeReviewerPlugin: Maintains a DB table that maps changesets to referenced tickets for code reviewing purposes.
     61== Additional Information and References ==
     63 * [apiref:trac.versioncontrol.api.IRepositoryChangeListener-class epydoc]
     64 * [apidoc:api/trac_versioncontrol_api#trac.versioncontrol.api.IRepositoryChangeListener API Reference]
     65  * 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]
     66 * [TracDev/DatabaseSchema/VersionControl Version control cache database schema]
     67 * Related tickets:
     68   * Generic change listener replacement: #8834, #11148, #6543, Trac-dev:7737
     69   * #9263: Requested an implementation of a `CommitMilestoneUpdater`.
     70   * #8732: Requested an implementation of a `CommitHoursUpdater` for time tracking.
     71   * #731: Requested an implementation of  a `CommitNotificationSender`.
     73=== API History
     74 * [wiki:TracDev/ApiChanges/0.12#IRepositoryChangeListener 0.12] introduced the interface (#7723, changeset:7961)