osimons@672: .. -*- mode: rst; encoding: utf-8 -*-
osimons@672: 
osimons@672: ==================
osimons@672: Build Notification
osimons@672: ==================
osimons@672: 
osimons@672: Introduction
osimons@672: ============
osimons@672: 
osimons@672: Bitten includes a mechanism to send out notification mails whenever a build
osimons@672: has failed (or succeeded, if required). 
osimons@672: 
osimons@672: The notification mails contain the revision number of the build, the author
osimons@672: name and the build log.
osimons@672: 
osimons@672: Notification Example:
osimons@672: 
osimons@672: .. code-block:: text
osimons@672: 
osimons@672:     Failed build of MyProject [32]
osimons@672:     ---------------------------------------------------------------------
osimons@672:     
osimons@672:     Changeset:             32 - <http://trac.mydomain.com/changeset/32>
osimons@672:     Committed by:          author
osimons@672: 
osimons@672:     Build Configuration:   main
osimons@672:     Build Slave:           client
osimons@672:     Build Number:          30 - <http://trac.mydomain.com/build/main/30> 
osimons@672:     
osimons@672:     Failed Steps:
osimons@672:     Failure Log:
osimons@672: 
osimons@672: 
osimons@672: Configuration
osimons@672: =============
osimons@672: 
osimons@672: The mechanism employs the trac notification system and uses most of its
osimons@672: options of the ``[notification]`` section of ``trac.ini``, specifically:
osimons@672: 
osimons@672: 
osimons@672: +-------------------------+--------------------------------------------------+
osimons@672: | Option                  | Description                                      |
osimons@672: +=========================+==================================================+
osimons@672: | ``smtp_enabled``        | activates mail notifications                     |
osimons@672: +-------------------------+--------------------------------------------------+
osimons@672: | ``smtp_default_domain`` | the domain to be appended to not fully qualified |
osimons@672: |                         | usernames                                        |
osimons@672: +-------------------------+--------------------------------------------------+
osimons@672: | ``smtp_server``         | the smtp server to use                           |
osimons@672: +-------------------------+--------------------------------------------------+
osimons@672: | ``smtp_user``           | smtp server username                             |
osimons@672: +-------------------------+--------------------------------------------------+
osimons@672: | ``smtp_password``       | smtp server password                             |
osimons@672: +-------------------------+--------------------------------------------------+
osimons@672: 
osimons@672: For an indepth description of the trac notification system and its options
osimons@672: please refer to the `Trac documentation`_.
osimons@672: 
osimons@672: .. _`trac documentation`: http://trac.edgewall.org/wiki/TracNotification
osimons@672: 
osimons@672: 
osimons@672: To further adjust the notification behaviour you can use the following
osimons@672: options:
osimons@672: 
osimons@672: +--------------------------------+-------------------------------------------+
osimons@672: | Option                         | Description                               |
osimons@672: +================================+===========================================+
osimons@672: | ``notify_on_failed_build``     | notifies on failed builds (defaults to    |
osimons@672: |                                | ``True``)                                 |
osimons@672: +--------------------------------+-------------------------------------------+
osimons@672: | ``notify_on_successful_build`` | notifies on successful builds (defaults   |
osimons@672: |                                | to ``False``)                             |
osimons@672: +--------------------------------+-------------------------------------------+
osimons@672: 
osimons@672: Configuration Example:
osimons@672: 
osimons@672: .. code-block:: ini
osimons@672: 
osimons@672:     [notification]
osimons@672:     smtp_enabled = true
osimons@672:     smtp_default_domain = mydomain.com
osimons@672:     smtp_server = smtp.mydomain.com
osimons@672:     smtp_user = admin@mydomain.com
osimons@672:     smtp_password = 12345
osimons@672:     notify_on_failed_build = true
osimons@672:     notify_on_successful_build = true
osimons@672: