[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

fx_example_tkt_local(n) 1 doc "FX - Extended Fossil Management"

Name

fx_example_tkt_local - fx - Example of Ticket Notifications - Full (local) access.

Table Of Contents

Synopsis

  • package require Tcl 8.5

Description

Welcome to fx, an application and set of packages providing extended management commands for the fossil SCM. This is an introductory document to fx, an application with supporting packages providing users of the Fossil SCM with extended management facilities going beyond the regular command line.

It is one in a set of related examples demonstrating the abilities of the system. The interested reader can then go on into to reference documentation via fx - Introduction to fx.

Background to the Example

  1. You have to generate notification emails for some or all changes to a fossil repository R.

  2. You have full access to the master repository file of the project.

  3. You are providing access to the project (file) through a web server under your control.

Solution to the Example

Basics

With full access to the main fossil project file there is no need for the basic setup a remote user has to go through to see the necessary configuration information.

We can jump directly to configuring mailing and routing.

Sending Mail

First we deal with the mail configuration. This is all about which host to use for injecting mail into the network, on which port, encrypted or not, the necessary credentials, etc.

Here are the relevant commands:

    fx repository set /path/to/the/fossil/repository/file
    fx note config set host     your-mail-host
    fx note config set user     your-mail-username
    fx note config set password your-mail-password
    fx note config set sender   your-project-maintainer-email-address
    fx note config set location your-projects-base-url
    fx note config export /path/to/mail-config-backup
    fx repository reset

Some notes:

  • The example uses the fx repository set|reset commands to avoid typing

        -R /path/to/the/fossil/repository/file
    

    in each configuration command of the example. This is just visual clutter. In actual scripts it is recommended to use -R however, as this allows the parallel execution of the script for different repositories. The set|reset commands involve global state, the "default repository", which forces serialization to avoid the script instances from interfering with each other.

  • The attributes host, user, and password should be self-explanatory. They are the mail host to talk to, as specified by your network administrator and/or ISP, and the credentials it expects to allow access.

    There is a port attribute as well, which needs to be set if and only if a non-standard port is used for SMTP.

    Similarly the tls attribute (a boolean) has to be set only if the mail system requires a TLS/SSL-encrypted connection.

  • The value of sender should be some thought put into. This email address will appear as the 'From' header in all generated mails. If a receiver of some notification has an issue they will likely respond to this address. Mail delivery errors, i.e. bounces will be sent to this address as well. Lastly, fx will send the stacktraces of all internal errors caught during operation there. As such it is strongly recommended to make this a proper and valid address, for the person or group which manages this setup.

  • The location is used in the generated mails as the base for the embedded links to the change artifacts, i.e. revisions, ticket changes, tickets, wiki pages, etc.

    In this case here, with direct access to the repository file, this part of the configuration must be set, as it cannot be infered.

  • Of all the settings above the location is the only one which is a decidedly per-repository item. For all other settings it makes sense to configure them at the global level, to be shared across all managed repositories. Assuming that there is more than one repository getting managed. To do so is as simple as adding the option --global to the configuration commands, like

        fx note config set --global host your-mail-host
    
  • The last command in the example, the note config export is technically not required, as it only makes a backup of the configuration in a text file.

    It is in the example due to my belief that having a backup, always, is good policy, and to drive this belief.

    And together with the complementary note config import command this is also another way of copying a mail setup around and applying it to multiple repositories.

Routing

Next after the low-level mail configuration we have to determine for which events of the timeline we wish to get notifications, and where to send them. This is called routing.

For our example we go with the simplest possible setup and declare that we are interested in all of them, and to send their notifications to the same address. The command for that is

    fx note route add all the-destination-email-address

Note that for clarity the option -R was left out of the command. Use either it or the "default repository", as shown in the previous section.

The all argument is a catch-all term for all possible events we might be interested in. Use the introspection command

    fx note route events

to list the possible events we can use instead of all.

The destination mail address can be anything, i.e. a single person, a mail alias, a mailing list, etc. The latter would allow people to subscribe to notifications from the repository without having to deal directly with it.

The above has handled the static routing. Destinations for notifications which are fixed for the repository and event.

For ticket changes we can further configure the dynamic routing. This enables the system to dynamically generate mail for the people involved in a ticket in some way, be it submitter, developer, commenter, etc.

This is done by telling the system which fields of a ticket can contain user names and/or email addresses. These are expanded through the account information of the repository into the addresses to send mail to, beyond the static destinations. The introspection command

   fx note route fields

will print a table of all ticket fields which are available. It is the maintainers responsibility to then declare which of them to inspect.

Using the Tcl core repository as an example the command declaring the fields to inspect is:

    fx note route field add assignee closer login private_contact submitter username

To capture changes to these fields themselves the system will automatically maintain an extended per-ticket history of the declared fields and send mail to both current and previous value of a field.

After the routing has been set up it is recommended to make a backup, using

    fx note route export /path/to/the/routes-backup

Having a backup is always good idea, I believe. And together with the complementary note route import command this enables us to apply the same routing setup to multiple repositories. Especially important as we currently do not support global shared routing.

Testing

While the setup is in principle done with the two previous sections I believe that it is a not good idea to immediately jump to the monitoring. Better test the setup first. To start, a general test that the configured mail settings work:

    fx test mail-setup 'Andreas Kupries <andreask@activestate.com>'

The command in the example sends a fixed mail to the specified destination address, using all the settings of section Sending Mail.

If that is ok, do

    fx note update-history

This command explicitly updates the cached history of the ticket fields mentioning for the dynamic routing (see last section).

The initial run can take some time, depending on the size of the pre-existing timeline, thus it feels nicer to me to do this separately instead of as part of the next group of commands.

    fx test manifest-parse --all
    fx test mail-receivers --all
    fx test mail-for       --all

These commands go over all the changes in the repository and checks that the system is able to parse their manifests, can generate a list of destination mail addresses for them, and generate mail for them.

Any problems will be shown in the resulting table.

This is less of a test of the repository and setup but more a test that the system can deal with all the data found in the repository. This is especially useful when operating on large repositories, like Tcl, Tk, etc. as this is essentially a stress-test of the tool internals, with a higher probability of testing even things which are usually not found or simply rare (like, for example, signed manifests, huge manifests, etc).

Nearly done

Now that we have configured all the big obvious things needed for the generation and distribution of the notifications we have one last thing to do:

    fx note mark-notified --all -R /path/to/the/fossil/repository/file

This tells fx that we do not wish to generate and send notification mails for everything which is already in the timeline of the project at this moment. This is especially important when setting up the notifications for a project which has already run for some time. The project's developers and ticket submitters will most emphatically not wish to receive a deluge of emails for changes which have already been done in the past.

Go

With all the preparatory work finally done we can go and start the monitoring. Note however that fx does not fully do everything by itself.

It assumes that it will be called from a cron job, i.e. that all the timing-related things are handled by the system, as is the prevention of multiple parallel notification runs, and where log files will be located.

As we have full access to the master fossil repository file of the project the only fx command we need in the core job script is note deliver, i.e.

    fx note deliver -R /path/to/the/fossil/repository/file

Getting new content and configuration changes, as is required for remote operation is not needed in this case.

More examples

  1. fx - Example of Ticket Notifications - Full remote access.

  2. fx - Example of Ticket Notifications - Limited remote access.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the fx Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.

Keywords

fossil, scm

Category

Fossil support