[[PageOutline(2-5,Contents,pullout)]] {{{ #!NewsFlash = News = 2012-11-04:: Major db code changes, '''requires a Trac environment upgrade''' `announcer-1.0dev` to address many pending issue. 2012-10-20:: Set the stage: On the way to `announcer-1.0` now, that should be compatible for Trac 0.11, but also will work up to current stable Trac 1.0. = !ToDo = * "downgrade db API code for compatibility with Trac 0.11 (currently only 0.12)" * fix more bugs * document current subscription API * release `announcer-1.0` }}} = Flexible notifications for Trac = == Overall description == The AnnouncerPlugin provides an alternative notification system, that can be used to completely replace the default [t:wiki:TracNotification TracNotification]. Improve '''users''' Trac experience.[[BR]] With growing number of both tickets and wiki pages, keeping yourself up-to-date on recent changes is a time consuming task and easy to miss some important information. The bigger your Trac application and user base, the more important is a flexible announcement system. At the very least, it will allow users to receive ''notices about attachments'', and to ''opt-out from receiving messages'' due to the always_notify_(owner|reporter|updater) options. AnnouncerPlugin has ''wiki subscription'' capabilities ^[1]^ and provides each registered user with a large set of options to adapt change notifications to individual demand. Get room for promising '''development'''.[[BR]] AnnouncerPlugin is as modular as Trac itself. It's easy to add new capabilities to the framework, i.e. see [wiki:WatchlistPlugin WatchlistPlugin] for easy ''per-wiki-page announcement'' registration and ''one-click ticket subscriptions'' challenging Trac's classic Cc ticket field. AnnouncerPlugin is meant to be agnostic to what is being watched, where you should send something (email, IRC, jabber, ...), and what format it should look at, so [wiki:AnnouncerPlugin/PluginSupport/FullBlogPlugin blog support] is barely the beginning. It has still a lot more possibilities to discover. The full system (in the not-too-distant-future) will allow users to 'subscribe' to certain events by specifying simple yet powerful rules, such as asking to receive an announcement for any change that involves a ticket with a priority greater then 'high'. AnnouncerPlugin is meant to be [t:wiki:TracDev/Proposals/Announcer '''the future of TracNotification''']. '''Secure''' your knowledge.[[BR]] While sharing all knowledge is a great idea in a perfect world, real-world businesses commonly rely on tight informational restrictions, that customers can rely on. In professional communication cryptographically signed and encrypted email is essential. AnnouncerPlugin will become a building block of this new [t:wiki:TracDev/TrustedTrac Trusted Trac] information management. It's OpenPGP support is [wiki:AnnouncerPlugin/MessageEncryption already on the way]. ^[1]^ see WikiNotificationPlugin for another approach AnnouncerPlugin extensions: * QuietPlugin == Installation and Configuration == === Prerequisites === * AnnouncerPlugin will only ever run on 0.11b1 or later. * While development is done with Trac 0.11 still in mind, i.e. to get full internationalization support you'll want to checkout from 'trunk' branch not before you have [http://babel.edgewall.org Babel] installed on your system. Beware: This plugin may break notifications from other Trac plugins that use the default [t:wiki:TracNotification TracNotification] system. A plugin that sends notifications using the !TracNotification system needs to be modified to use the AnnouncerPlugin API. For example, see the aforementioned [AnnouncerPlugin/PluginSupport/FullBlogPlugin FullBlogPlugin]. === Download === * Download the zipped source from ~~[download:announcerplugin/0.11 0.11]~~, ~~[download:announcerplugin/0.12 0.12]~~ or [download:announcerplugin/trunk trunk]. * You can check out AnnouncerPlugin from [/svn/announcerplugin here] using Subversion, or [source:announcerplugin browse the source] with Trac. '''Note:''' Don't use anything older than current `trunk`, or be prepared to at least loose some/all of your settings when upgrading. This might, but is not guaranteed to get addressed later on due to a number of rather experimental db schema versions (see comments in [12296] to [12302] for details.) After installing AnnouncerPlugin, be sure to run `trac-admin /path/to/env upgrade`. This is needed because the plugin adds two tables to the Trac db. The upgrade script allows the plugin to create the needed table or update any older schema. Note though, that data conversion is still worked on and even might never get fully done for the more ancient revisions. As of r3107 (dubbed v0.2), the AnnouncerPlugin has been working (for me!) in a basic way in our corporate Trac installation. This includes all the mentioned modules above, in particular the notification of Wiki additions/changes/deletions to anyone interested, 'watching' interesting resources, HTML ticket notifications, and such. The email distribution is not as stable and complete as the default [t:wiki:TracNotification TracNotifications] yet; there are options that are not yet taken into account, and a lot of stuff particularly focused around codecs that are simply ignored right now. That isn't to say it won't work, just that you should be prepared for errors if you're ambitious enough to use it until more people have tried it. :) === Installation === The easiest way to install AnnouncerPlugin is to simply point easy_install from the t-h.o SVN repository, a la: {{{ #!python easy_install http://trac-hacks.org/svn/announcerplugin/trunk }}} Alternatively, you may download the source via one of the above methods, go into the `trunk` directory and then run: {{{ #!python python setup.py install }}} For the newer branches (`0.12`/`trunk`) see the i18n/l10n section below for an '''[#Abouti18nl10nsupport important hint on egg creation]''' that applies to system wide installations as well. ==== Development Environment ==== Scroll to the [#DevelopmentVersion DevelopmentVersion] for a quick development environment setup. === Central configuration === ==== Fast path ==== For a system that is basically compatible with your existing setup and allowing minimally invasive wiki features, the following is suggested in trac.ini: {{{ #!ini [components] announcer.* = enabled [announcer] email_enabled = true }}} If you are still using `0.11`, you'll need `smtp_enabled` instead of `email_enabled`. See the TracIni page after installation for additional available options. ==== Save on migration ==== If you configured the [t:wiki:TracNotification TracNotification] system before, another approach to Announcer configuration is to simply rename the `[notification]` section in your ''trac.ini'' to `[announcer]`. Where possible, the option names are the same. Additional options that may be available are specified above in the modules section. ==== Deep waters ==== After you have installed the AnnouncerPlugin, you should carefully evaluate the modules you wish to use and enable them. The simplest method of doing this is through Trac's built in admin panels. The following recommendations should make decisions easier: * Producers - ''It is recommended you enable all of the producers; they are the source of events that are fed into the !AnnouncementSystem.'' * '''!TicketChangeProducer''' * '''!WikiChangeProducer''' * '''!AttachmentChangeProducer''' * Subscribers - ''Evaluate the descriptions of the subscriber modules above, and decide which features you want users to support.'' * ''For compatiblity with your current setup, the following are recommended:'' * '''!LegacyTicketSubscriber''' * '''!StaticTicketSubscriber''' (if you use smtp_always_bcc) * '''!CarbonCopySubscriber''' * ''Additional options that are recommended: '' * '''!WatchSubscriber''' (to allow the user to ''Watch'' tickets or wiki entries; if you use this its possible to replace existing CC functionality with this more privacy-aware option) * '''!GeneralWikiSubscriber''' * ''Possibly useful:'' * '''!JoinableGroupSubscriber''' (this was more of a proof-of-concept then anything else; but with !WatchSubscriber above and a disabled !CarbonCopySubscriber, it can allow you to completely redefine the CC field) * Distributors - ''Only '''!EmailDistributor''' is available at this point, so is essentially required.'' * Formatters - ''It is recommended that both formatter modules be enabled. If one is disabled, then events from that specified realm will never be able to be sent to anyone.'' * '''!TicketEmailFormatter''' * '''!WikiEmailFormatter''' * Resolvers - ''For all subscriptions besides those sent from !CarbonCopySubscriber, a resolver must be present to translate a name into an address'' * '''!SessionEmailResolver''' (recommended, will use the session's email address (authenticated or otherwise) to send mail) * '''!DefaultDomainEmailResolver''' (recommended if you used the smtp_default_domain option previously) * '''!SpecifiedEmailResolver''' (not recommended-- a proof of concept if nothing else) For better collaborate with the [WatchlistPlugin#AnnouncerPlugin WatchlistPlugin] the two contextual navigation items ''Watch This''/''Unwatch This'' on the wiki page can be renamed by specifying the following in the `[announcer]` section. An empty value removes them completely. {{{ #!ini ctxtnav_names = Notify me, Do not notify me }}} === Modular per-user configuration === The plugin itself is very modular, and exactly what features you have will depend on which modules you enable. You select modules in the 'Plugins' page of the 'Admin' section of your trac as stated the [#Centralconfiguration previous section]. ==== Legacy Modules ==== These mimic the standard trac notification that has been in Trac for awhile. In all cases, they are configured via the [announcer] section of the trac.ini. In most cases, the options are identical to what was previously in the [notification] section. In fact its recommended that you simply rename [notification] to [announcer] if you are going to be using any of these compatibility modules. * ''!StaticTicketSubscriber'': If enabled, this module will obey the ''smtp_always_bcc'' option to deliver a copy of every announcement sent out to a single address. * ''!LegacyTicketSubscriber'': If enabled, this module will obey the ''always_notify_owner'', ''always_notify_reporter'' and ''always_notify_updater'' option, except that individual users may choose to opt-out of this on a per-option basis. So if you don't want to receive messages just because you are the reporter, you can uncheck that. * ''!CarbonCopySubscriber'': If enabled, any name (or address) put into the CC field of a ticket will receive a notification. ''Note'': I recommend you turn this off and instead use the CC field for groups and the Watch This feature for CC's! See below. [[Image(TicketNotificationPreferences.png)]] ==== Groups ==== With the ''joinable_groups'' option in the [announcer] section, the Trac Admins can create any number of joinable groups. Any users may then in their preferences choose to join them by simply clicking to opt-into the membership. This feature is provided by ''!JoinableGroupSubscriber'', and is meant to create targeted groups of people that should be notified about certain important issues. One example might be 'security' that security-related bugs should notify everyone about. Another might be 'sitedown' that represents a critical failure at a customer's site where you want to be sure to notify certain high level management in your company. In any case, by prepending the group with an @ and adding it into the CC box, everyone who has opted into that group will receive notification of changes to that ticket. E.g., adding '@security' to the CC field will send the security team a message whenever someone alters it. The !CarbonCopySubscriber ignores any such entries (if its enabled at all) Configure like so: {{{ #!ini [announcer] joinable_groups = group1,group2,group3 }}} [[Image(AnnouncerPlugin:Groups-Prefs.jpg)]] ==== Watches ==== If ''!WatchSubscriber'' is enabled, then in the context-sensitive navigation portion of each ticket and wiki page, a 'Watch This' link will be provided. Clicking on it will add you to the watch list for the resource-- any changes to it will be sent to you. This can be in addition to the CC field if you have !CarbonCopySubscriber enabled, or you can use it to replace the functionality. When a page is already watched, the link changes to 'Unwatch This' [[Image(AnnouncerPlugin:WatchThis.png)]] ==== General Wiki ==== If you would like to receive more general notice of wiki changes, you can use the ''!GeneralWikiSubscriber''. With it you may specify any number of patterns, and if they match a wiki page name, you'll receive a notice if that page is created, edited, deleted, or such. In particular, you may use a pattern of '*' and you'll see any wiki changes that happen on the site. This is particularly useful in situations where the wiki uses a hierarchal structure; so if you use a pattern such as 'Project*', then 'Project/Plan' and 'Project/Concerns' will all match. [[Image(AnnouncerPlugin:GeneralWiki.png)]] ==== Formatters ==== For tickets, both a plain text and HTML formatter are currently supplied, and you may choose which you wish to receive in your preferences. For wiki pages, only a plain text notice is currently available. The HTML formatter also sends out a plain text alternative for those email clients that may not support HTML email. Ticket change messages are build from Genshi text template `ticket_email_plaintext.txt`. Additionally the following trac.ini options are available to configure the ticket formatter: ticket_email_subject:: Determines the subject of the email that is sent out. Defaults to ''Ticket #${ticket.id}: ${ticket!['summary']}''. ticket_email_header_fields:: A list of fields that are always sent at the top of the email notification; Defaults to ''owner, reporter, milestone, priority, severity''. [[Image(AnnouncerPlugin:HtmlEmail.jpg)]] ==== Distributors ==== Although the goal is to allow many kinds of distribution, at this point we're only delivering to email addresses. The ''!EmailDistributor'' uses the same options as the old trac notification, just (as above) in the ''announcer'' section and not the ''notification'' section. Some options it doesn't quite use yet but will in the future. There are a few additional ones: * use_threaded_delivery: If Python is built with threads, this option will speed up actual delivery by a second or two-- that's not a long time, but it's time not spent delaying a request from going through. * default_email_format: This should be either 'text/plain' or 'text/html' and represents the default format that it sends email as. Users may override this in their preferences. * email_address_resolvers: An ordered list of resolvers (see below) that the distributor uses to map usernames to email addresses. The first one that returns an address, wins. ==== Resolvers ==== Currently, the following resolvers can be configured to map usernames to email addresses: * ''!DefaultDomainEmailResolver'': This will simply blindly append the domain specified in [announcer] smtp_default_domain onto the end of the username. * ''!SpecifiedEmailResolver'': This will allow the user to override the email address in Trac (or anywhere else) to demand all email be sent to a certain address specified in their user preferences (and separate from Trac's normal address) * ''!SessionEmailResolver'': This will retrieve the email address associated with the username's Trac session. The order is important: If you specify resolvers as {{{ #!ini [announcer] email_address_resolvers = DefaultDomainEmailResolver, SpecifiedEmailResolver, SessionEmailResolver }}} then the only resolver, that will ever be checked, would be !DefaultDomainEmailResolver -- it blindly appends a domain name, after all. Its best for last. The recommended setting is: {{{ [announcer] email_address_resolvers = SpecifiedEmailResolver, SessionEmailResolver }}} Unless you're in an intranet setup and !DefaultDomainEmailResolver is appropriate at the end. === Plugins === The AnnouncerPlugin has plugins to support the following Trac plugins: [[TitleIndex(AnnouncerPlugin/PluginSupport/)]] == Bugs/Feature Requests == total issue of record: [[TicketQuery(component=AnnouncerPlugin,format=progress)]] open issues by type: [[TicketQuery(component=AnnouncerPlugin,status!=closed&group=type,format=progress)]] If you have any issues that is not found in [query:?component=AnnouncerPlugin&order=priority existing tickets], create a [http://trac-hacks.org/newticket?component=AnnouncerPlugin&owner=hasienda new ticket], please. == Development Version == The trunk branch is under development again. Despite AnnouncerPlugin was already developed against Trac 0.12 and Python2.6 before, we're reaching back to Trac 0.11 and Python2.4 again (see #9106), before branching out and following Trac 1.0 for all great new features. If you upgrade from early versions of AnnouncerPlugin, be prepared for a number of changes, even in the name space '''AnnouncerPlugin becomes TracAnnouncer'''. You will need to edit your `trac.ini` components section accordingly (announcerplugin -> announcer). There are many other module changes, so it's probably best to use the Trac plugin admin to configure TracAnnouncer after an upgrade. As stated before, as of [8087] there is preliminary support for sending encrypted and/or cryptographically signed emails. OpenPGP support provided by [http://www.gnupg.org/ GnuPG] should be barely working by now as an intermediate solutions, but this will be rebased on CryptoPlugin methods later on. See more details at the corresponding [wiki:AnnouncerPlugin/MessageEncryption development page]. Email delivery configuration has been changed significantly. Sendmail functionality has been added. SMTP configuration has been split out into it's own section. Save yourself some trouble and install !IniAdmin. See new settings with default [#EmailConfig below]. Want to get started hacking TracAnnouncer? Here's what I would do. Replace vim with the editor of your choice. Replace git with the SCM of your choice. 1. Make sure you have virtualenv installed 1. Get the code {{{ #!sh ~ $ cd src ~/src $ git svn init http://trac-hacks.org/svn th-announcer ~/src $ cd th-announcer ~/src/th-announcer $ vim .git/config ~/src/th-announcer $ cat .git/config [core] repositoryformatversion = 0 filemode = true bare = false logallrefupdates = true autocrlf = false [svn-remote "svn"] url = http://trac-hacks.org/svn fetch = announcerplugin/trunk:refs/remotes/git-svn/trunk fetch = announcerplugin/0.11:refs/remotes/git-svn/0.11 fetch = announcerplugin/0.11dev:refs/remotes/git-svn/0.11dev ~/src/th-announcer $ git svn fetch git blah blah ~/src/th-announcer $ git checkout -b trunk git-svn/trunk more blah blah }}} 1. Setup a virtualenv and install everything in it {{{ #!sh ~/src/th-announcer $ cd ~ $ virtualenv th-announcer ~ $ . th-announcer/bin/activate (th-announcer)~ $ pip install -U Babel Trac pysqlite pip blah blah (th-announcer)~ $ cd src/th-announcer (th-announcer)~/src/th-announcer $ python ./setup.py compile_catalog -f (th-announcer)~/src/th-announcer $ python setup.py develop }}} 1. It is also very helpful to install iniadmin `pip install -U http://trac-hacks.org/svn/iniadminplugin/0.11` 1. Create a trac instance for testing `trac-admin ~/th-announcer/trac initenv` 1. Add `root` as a TRAC_ADMIN `trac-admin ~/th-announcer/trac/ permission add root TRAC_ADMIN` 1. Create an htpasswd file so you can log in: `echo root:Xy2PtsPf0839Y > ~/th-announcer/trac/htpasswd` (that's 'password') 1. Fire her up! `cd ~/th-announcer/trac && tracd -p 7421 . -sr --basic-auth *,${HOME}/th-announcer/trac/htpasswd,*` 1. Browse to it. `chromium http://localhost:7421/admin` and login as root:password 1. Enable all the announcer and iniadmin stuff. 1. Edit your config with iniadmin. === About i18n/l10n support === The development version of this plugin is prepared for localization. After recent major changes an additional name-space has been introduced to separate maintenance efforts from development for upcoming versions. Be part of the shift, prefer contributions to the new stuff.[[BR]] But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 1. look, if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tracannouncer Transifex] (catalogs for [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/announcer older versions] available as well) or 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details). You've done a new translation? Superb! Contributing your translation is highly appreciated. You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: Top translations: Trac_Plugin-L10N ยป [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tracannouncer/ tracannouncer][[BR]] [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tracannouncer/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tracannouncer/)]] Kindly provided by [[Image(https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]] Preparing the plugin from source requires '''no additional steps''' for compiling message catalog files. Only to include translations marked as `# fuzzy` by the translator, you'll want to do a manual message catalog compilation with the extra `-f` argument before packaging: {{{ #!sh cd announcer python ./setup.py egg_info python ./setup.py compile_catalog -f python ./setup.py bdist_egg }}} Due to a know Trac issue Babel has to be installed prior to Trac, to get it all working as expected.[[BR]] Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. === Email Config === {{{ #!ini [announcer] default_email_format = text/plain email_address_resolvers = SpecifiedEmailResolver, SessionEmailResolver, DefaultDomainEmailResolver email_enabled = true email_from = trac@localhost email_from_name = email_replyto = trac@localhost email_sender = SmtpEmailSender email_subject_prefix = __default__ email_to = undisclosed-recipients: ; mime_encoding = base64 use_public_cc = false use_threaded_delivery = false [smtp] debuglevel = 0 server = localhost timeout = 10 port = 25 user = password = use_tls = false use_ssl = false [sendmail] sendmail_path = sendmail }}} == Recent Changes == [[ChangeLog(announcerplugin, 3)]] == Author/Contributors == '''Authors:''' [wiki:ixokai], [wiki:doki_pen][[BR]] '''Maintainer:''' [wiki:hasienda][[BR]] '''Contributors:''' [wiki:doki_pen], [wiki:ebray], [wiki:jun66j5], [wiki:leorochael], [wiki:mixedpuppy], [wiki:olistudent], [wiki:rea], [wiki:rjollos], [wiki:spcamp], [wiki:slestak]