Changes between Version 76 and Version 77 of AnnouncerPlugin


Ignore:
Timestamp:
Mar 9, 2015, 1:43:59 PM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • AnnouncerPlugin

    v76 v77  
    1414}}}
    1515
    16 = Flexible notifications for Trac =
    17 == Overall description ==
     16= Flexible notifications for Trac
     17
     18== Description
    1819
    1920The AnnouncerPlugin provides an alternative notification system, that can be used to completely replace the default [t:wiki:TracNotification TracNotification].
    2021
    21 Improve '''users''' Trac experience.[[BR]]
     22=== Improve '''users''' Trac experience
     23
    2224With 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.
    2325
    24 Get room for promising '''development'''.[[BR]]
    25 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'''].
    26 
    27 '''Secure''' your knowledge.[[BR]]
    28 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].
     26=== Get room for promising '''development'''
     27
     28AnnouncerPlugin is as modular as Trac itself. It's easy to add new capabilities to the framework, ie 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. The full system 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 than 'high'. AnnouncerPlugin is meant to be [t:wiki:TracDev/Proposals/Announcer '''the future of TracNotification'''].
     29
     30=== '''Secure''' your knowledge
     31
     32While 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. OpenPGP support is [wiki:AnnouncerPlugin/MessageEncryption on the way].
    2933
    3034^[1]^ see WikiNotificationPlugin for another approach
    … …  
    3337 * QuietPlugin
    3438
    35 == Installation and Configuration ==
    36 
    37 === Prerequisites ===
    38 
    39  * AnnouncerPlugin will only ever run on 0.11b1 or later.
     39== Installation and Configuration
     40
     41=== Prerequisites
     42
     43 * AnnouncerPlugin will only ever run on Trac 0.11b1 or later.
    4044 * 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.
    4145 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].
    4246
    43 === Download ===
     47=== Download
    4448
    4549 * Download the zipped source from ~~[download:announcerplugin/0.11 0.11]~~, ~~[download:announcerplugin/0.12 0.12]~~ or [download:announcerplugin/trunk trunk].
    4650 * You can check out AnnouncerPlugin from [/svn/announcerplugin here] using Subversion, or [source:announcerplugin browse the source] with Trac.
    4751
    48 '''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.)
    49 
    50 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.
    51 
    52 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.
    53 
    54 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. :)
    55 
    56 === Installation ===
    57 
    58 The easiest way to install AnnouncerPlugin is to simply point easy_install from the t-h.o SVN repository, a la:
     52'''Note:''' Don't use anything older than current `trunk`, or be prepared to lose some 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]).
     53
     54After installing AnnouncerPlugin, 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.
     55
     56As of r3107 (dubbed v0.2), the AnnouncerPlugin has been working 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.
     57
     58The 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. So while it could still work, there could be errors.
     59
     60=== Installation
     61
     62The easiest way to install AnnouncerPlugin is to use easy_install from the t-h.o SVN repository:
    5963
    6064{{{
    6165#!python
    62  easy_install http://trac-hacks.org/svn/announcerplugin/trunk
     66easy_install http://trac-hacks.org/svn/announcerplugin/trunk
    6367}}}
    6468
    … …  
    6771{{{
    6872#!python
    69  python setup.py install
     73python setup.py install
    7074}}}
    7175
    7276For 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.
    7377
    74 ==== Development Environment ====
     78==== Development Environment
    7579
    7680Scroll to the [#DevelopmentVersion DevelopmentVersion] for a quick development environment setup.
    7781
    78 === Central configuration ===
    79 ==== Fast path ====
    80 
    81 For a system that is basically compatible with your existing setup and allowing minimally invasive wiki features, the following is suggested in trac.ini:
     82=== Central configuration
     83
     84==== Fast path
     85
     86For a system that is basically compatible with your existing setup and allowing minimally invasive wiki features, the following is suggested in `trac.ini`:
    8287
    8388{{{
    … …  
    9095}}}
    9196
    92 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.
    93 
    94 ==== Save on migration ====
     97If you are still using Trac 0.11, you'll need `smtp_enabled` instead of `email_enabled`. See the TracIni page after installation for additional available options.
     98
     99==== Save on migration
    95100
    96101If 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.
    97102
    98 ==== Deep waters ====
    99 
    100 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:
     103==== Deep waters
     104
     105After 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:
    101106
    102107 * Producers - ''It is recommended you enable all of the producers; they are the source of events that are fed into the !AnnouncementSystem.''
    … …  
    123128  * '''!SpecifiedEmailResolver''' (not recommended-- a proof of concept if nothing else)
    124129
    125 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.
     130To 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.
    126131{{{
    127132#!ini
    … …  
    129134}}}
    130135
    131 === Modular per-user configuration ===
     136=== Modular per-user configuration
    132137
    133138The 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].
    134139
    135 ==== Legacy Modules ====
     140==== Legacy Modules
    136141
    137142These 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.
    … …  
    145150[[Image(TicketNotificationPreferences.png)]]
    146151
    147 ==== Groups ====
     152==== Groups
    148153
    149154With 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.
    … …  
    162167[[Image(AnnouncerPlugin:Groups-Prefs.jpg)]]
    163168
    164 ==== Watches ====
     169==== Watches
    165170
    166171If ''!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'
    … …  
    168173[[Image(AnnouncerPlugin:WatchThis.png)]]
    169174
    170 ==== General Wiki ====
     175==== General Wiki
    171176
    172177If 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.
    … …  
    178183[[Image(AnnouncerPlugin:GeneralWiki.png)]]
    179184
    180 ==== Formatters ====
     185==== Formatters
    181186
    182187For tickets, both a plain text and HTML formatter are currently supplied, and you may choose which you wish to receive in your preferences. In the version 1.0 and later of the plugin, the preference is available in the //Subscription// section after at least one rule has been specified. For wiki pages, only a plain text notice is currently available.
    … …  
    193198[[Image(AnnouncerPlugin:HtmlEmail.jpg)]]
    194199
    195 
    196 ==== Distributors ====
     200==== Distributors
    197201
    198202Although 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.
    … …  
    203207 * 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.
    204208
    205 ==== Resolvers ====
     209==== Resolvers
    206210
    207211Currently, the following resolvers can be configured to map usernames to email addresses:
    … …  
    211215 * ''!SessionEmailResolver'': This will retrieve the email address associated with the username's Trac session.
    212216
    213 The order is important: If you specify resolvers as
     217The order is important. If you specify resolvers as follows:
    214218
    215219{{{
    … …  
    219223}}}
    220224
    221 then the only resolver, that will ever be checked, would be !DefaultDomainEmailResolver -- it blindly appends a domain name, after all. Its best for last.
     225then the only resolver, that will ever be checked, would be !DefaultDomainEmailResolver, it blindly appends a domain name, after all.
    222226
    223227The recommended setting is:
    … …  
    230234Unless you're in an intranet setup and !DefaultDomainEmailResolver is appropriate at the end.
    231235
    232 === Plugins ===
     236=== Plugins
    233237
    234238The AnnouncerPlugin has plugins to support the following Trac plugins:
    235239[[TitleIndex(AnnouncerPlugin/PluginSupport/)]]
    236240
    237 == Bugs/Feature Requests ==
    238 
    239 total issue of record:
    240 [[TicketQuery(component=AnnouncerPlugin,format=progress)]]
    241 open issues by type:
    242  [[TicketQuery(component=AnnouncerPlugin,status!=closed&group=type,format=progress)]]
    243 
    244 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.
    245 
    246 == Development Version ==
    247 
    248 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.
     241== Bugs/Feature Requests
     242
     243Existing bugs and feature requests for WantedPagesMacro are [report:9?COMPONENT=AnnouncerPlugin here].
     244
     245If you have any issues, create a [http://trac-hacks.org/newticket?component=AnnouncerPlugin&owner=hasienda new ticket].
     246
     247[[TicketQuery(component=AnnouncerPlugin&group=type,format=progress)]]
     248
     249== Development Version
     250
     251The 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 new features.
    249252
    250253If 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.
    … …  
    254257Email 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].
    255258
    256 
    257 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.
    258 
    259  1. Make sure you have virtualenv installed
    260  1. Get the code
     259Want 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.
     260
     261 1. Make sure you have virtualenv installed.
     262 1. Get the code:
    261263{{{
    262264#!sh
    … …  
    282284more blah blah
    283285}}}
    284  1. Setup a virtualenv and install everything in it
     286 1. Setup a virtualenv and install everything in it:
    285287{{{
    286288#!sh
    … …  
    294296(th-announcer)~/src/th-announcer $ python setup.py develop
    295297}}}
    296  1. It is also very helpful to install iniadmin `pip install -U http://trac-hacks.org/svn/iniadminplugin/0.11`
    297  1. Create a trac instance for testing `trac-admin ~/th-announcer/trac initenv`
    298  1. Add `root` as a TRAC_ADMIN `trac-admin ~/th-announcer/trac/ permission add root TRAC_ADMIN`
    299  1. Create an htpasswd file so you can log in: `echo root:Xy2PtsPf0839Y > ~/th-announcer/trac/htpasswd` (that's 'password')
    300  1. Fire her up! `cd ~/th-announcer/trac && tracd -p 7421 . -sr --basic-auth *,${HOME}/th-announcer/trac/htpasswd,*`
    301  1. Browse to it. `chromium http://localhost:7421/admin` and login as root:password
     298 1. It is also very helpful to install iniadmin `pip install -U http://trac-hacks.org/svn/iniadminplugin/0.11`.
     299 1. Create a trac instance for testing `trac-admin ~/th-announcer/trac initenv`.
     300 1. Add `root` as a TRAC_ADMIN `trac-admin ~/th-announcer/trac/ permission add root TRAC_ADMIN`.
     301 1. Create an htpasswd file so you can log in: `echo root:Xy2PtsPf0839Y > ~/th-announcer/trac/htpasswd` (that's 'password').
     302 1. Fire her up! `cd ~/th-announcer/trac && tracd -p 7421 . -sr --basic-auth *,${HOME}/th-announcer/trac/htpasswd,*`.
     303 1. Browse to it. `chromium http://localhost:7421/admin` and login as root:password.
    302304 1. Enable all the announcer and iniadmin stuff.
    303305 1. Edit your config with iniadmin.
    304306
    305 === About i18n/l10n support ===
     307=== About i18n/l10n support
    306308
    307309The 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]]
    … …  
    310312 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details).
    311313
    312 You've done a new translation? Superb! Contributing your translation is highly appreciated.
    313 
    314 You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project]
    315 via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]:
     314Contributing 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]:
    316315
    317316Top translations: Trac_Plugin-L10N » [http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracannouncer/ tracannouncer][[BR]]
    … …  
    330329Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins].
    331330
    332 === Email Config ===
     331=== Email Config
     332
     333Add the following to your `trac.ini` file:
    333334
    334335{{{
    … …  
    362363}}}
    363364
    364 == Recent Changes ==
     365== Recent Changes
    365366
    366367[[ChangeLog(announcerplugin, 3)]]
    367368
    368 == Author/Contributors ==
     369== Author/Contributors
    369370
    370371'''Authors:''' [wiki:ixokai], [wiki:doki_pen][[BR]]
    371 '''Maintainer:''' [wiki:hasienda][[BR]]
     372'''Maintainer:''' [[Maintainer]][[BR]]
    372373'''Contributors:''' [wiki:doki_pen], [wiki:ebray], [wiki:jun66j5], [wiki:leorochael], [wiki:mixedpuppy], [wiki:olistudent], [wiki:rea], [wiki:rjollos], [wiki:spcamp], [wiki:slestak]