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

Basics

The key to the solution demonstrated here is to transform the case from remote access to local access. At that point most of fx - Example of Ticket Notifications - Full (local) access. can be applied, with some modifications which ensure that all relevant pieces of the local repository are kept up to date.

First choose a directory D to work in, then create a local clone C of the project repository R in D.

As we are not a superuser we cannot get the configuration areas required for dynamic routing (see section Routing).

As the last steps make a backup copy of the clone. It is always a good idea to have a backup.

Here it means that problems in the coming section only require copying the backup back into place instead of having to perform another (expensive) clone operation over the network. All of the above in a generalized example:

    cd /the/chosen/directory
    USER=your-account
    PASS=your-password
    REMOTE="http://${USER}:${PASS}@remote-host/path/to/project"
    fossil clone $REMOTE source.fossil
    cp source.fossil source.fossil.bak

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 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.

• Note that the attribute location is not configured. As we are using a local clone of a remote project this information can be and is infered from the remote url we cloned from.

• 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 normally can further configure the dynamic routing which enables the system to dynamically generate mail for the people involved in a ticket in some way, be it submitter, developer, commenter, etc. However as a regular user we do not have access to the configuration required for this, i.e. the areas users and email. So, in the situation of this example dynamic routing is simply not possible.

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 no direct access to the master fossil repository file of the project we not only have to generate and send mail, but also have to make sure that our local clone is kept up to date. Remember however that we do not access to the configuration, only content.

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