Bug#928041: systemd: please document the recommended way to add a systemd timer to a package

[Francesco Poli (wintermute)]

Package: systemd
Version: 241-3
Severity: normal

Hello,
the other day I noticed that lintian pointed out a new missing piece
in my package (apt-listbugs):
missing-systemd-timer-for-cron-script

Basically, it alerts me that my package ships a cron.daily script,
without shipping a corresponding systemd timer.

Hence, I began doing some research on the proper way to ship a
systemd timer along with an equivalent cron script (while avoiding
conflicts between the two).
I looked for examples in other packages (such as man-db and
logrotate).
I am starting to get an idea of how to set this up, but some aspects
are still unclear.

My main needs are:

 a) the script (to be executed by the systemd timer) may generate
    output: this output should be sent to root at localhost via local
    mail (if a sendmail-compatible MTA is installed and able to
    deliver local mail)
 
 b) the cron.daily job should not run, if systemd is installed
    and used as PID 1

I searched for documentation about the recommended Debian way to add a
systemd timer to a package, but failed to find much.

The Debian Policy manual talks about [cron jobs], but does not seem
to mention systemd timers. There seems to be an [open bug report]
about this, which also [mentions] the need to avoid running cron jobs
which are superseded by systemd timers.

I found some information about the need to send local mail on
the [archlinux wiki], but the suggested workaround looks inconvenient
(since it requires writing a dedicated script for something
that cron provides out of the box!) and suitable for failing
jobs only (while I need to send local mail, whenever the job generates
output)...

[cron jobs]: <https://www.debian.org/doc/debian-policy/ch-opersys.html#cron-jobs>
[open bug report]: <https://bugs.debian.org/770440>
[mentions]: <https://bugs.debian.org/770440#20>
[archlinux wiki]: <https://wiki.archlinux.org/index.php/Systemd/Timers#Caveats>


Could you please document the recommended Debian way to add a
systemd timer to a package, which also ships a cron job?

Thanks for your time and for any help you may provide.
Bye.