fx_example_tkt_local - fx - Example of Ticket Notifications - Full (local) access.
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.
You have to generate notification emails for some or all changes to a fossil repository R.
You have full access to the master repository file of the project.
You are providing access to the project (file) through a web server under your control.
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.
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.
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.
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).
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.
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.
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.
Fossil support