Woof! 🐕

Woof! monitors updates sent to a mailing list.

Plug Woof! to a mailbox subscribed to a mailing list, and Woof! will monitor updates about user-significant changes, help requests, bugs, patches and new releases.

Subscribers of the list can trigger Woof! by using specific words either in the subject (for patches) or in the body (for bugs).

All updates (for bugs, patches, help requests and new releases) can be triggered by using specific X-Woof-* mail headers.

Basic usage

Here are the triggers allows to manage bugs and patches:

• Confirmed in the body of the email registers a new bug.
• Fixed in the body of an email marks the bug in the same thread as fixed.
• [PATCH] or [PATCH x/x] in the subject of a new email registers a new patch.
• Applied in the body of an email marks the patch in the same thread as applied.

Applied, Confirmed and Fixed should be placed at the beginning of a line in a plain-text email. Beware that the match is case-sensitive, so “applied”, “CONFIRMED” and “FiXeD” won’t work.

Advanced usage

You can control the Woof database entirely by adding headers in your replies to a mailing list.

Woof headers

X-Woof-Bug

Confirm a bug or close it.

X-Woof-Patch

Declare a patch or mark it as applied.

X-Woof-Help

Request help or cancel the request.

X-Woof-Change

Announce a change or dismiss it.

X-Woof-Release

Announce a release or dismiss it.

Announce a release

From: xxx@xxx.xx
X-Woof-Release: 10.2
...

will declare 10.2 as a new release.

Confirm a bug

From: xxx@xxx.xx
X-Woof-Bug: confirmed
...

will mark a bug discussed in a thread as confirmed (see synonyms below.)

Mark a bug as fixed

From: xxx@xxx.xx
X-Woof-Bug: fixed
...

will mark the bug discussed in a thread as fixed (see synonyms below.)

Mark a patch as applied

Any email with a subject containing a substring like [PATCH] or [PATCH x/x] will be referenced as proposing a new patch, without requiring a specific Woof! header.

From: xxx@xxx.xx
X-Woof-Patch: applied
...

will mark a patch as applied.

Declare a patch

If someone attaches a patch and forget to add [PATCH] at the beginning of the subject, you can forward the email to the Woof! mailbox and add this header:

X-Woof-Patch: confirmed

Request help

From: xxx@xxx.xx
X-Woof-Help: confirmed
...

will add a request for help.

Cancel a help request

From: xxx@xxx.xx
X-Woof-Help: canceled
...

will cancel the help request from within this thread.

Announce a change

From: xxx@xxx.xx
X-Woof-Change: 1234567879 8.4
...

will declare commit 1234567879 as an upcoming change for the future release version 8.4. When the 8.4 release is done, the change will not be advertized anymore.

From: xxx@xxx.xx
X-Woof-Change: 1234567879 8.4.2 8.5
...

will declare commit 1234567879 as an upcoming change for the future release versions 8.4 or 8.5. If, for any reason, version 8.4.2 is not released and version 8.5 is released instead, the change will not be advertized anymore.

You can also omit the commit:

From: xxx@xxx.xx
X-Woof-Change: 8.4
...

Note that in this case, only one version is allowed.

Cancel a change announcement

From: xxx@xxx.xx
X-Woof-Change: cancel
...

will cancel the change that was announced within this thread.

Annotations for bugs and help requests

By default, the summary for bugs and help requests is the subject of the email with the X-Woof-Bug or X-Woof-Help header.

Sometimes, the subject of the email is not specific enough and you don’t want to start a subthread by changing the subject while replying to a list.

Instead, you can simply use the X-Woof-Bug or X-Woof-Help headers to add your summary. For example:

From: xxx@xxx.xx
X-Woof-Bug: X does Y instead of doing Z, as expected.
...

will mark the bug discussed in a thread as confirmed and use X does Y instead of doing Z, as expected. as the summary for this bug.

Synonyms

• confirmed, true, t
• canceled, cancel, closed, close, done, fixed, nil.

Configure

You need to set some environment variables to let the application run.

See src/bzg/config.clj for the list of required variables.

Run this to check your configuration:

~$ cd woof/
~$ clj -M:test:runner

Run

~$ cd woof/
~$ clj -M:run

Deploy

~$ cd woof/
~$ clj -M:uberdeps
~$ java -cp target/woof.jar clojure.main -m bzg.web

Contribute

Woof is alpha software. It is being tested to advertize updates from Org-mode but you should be able to use it for any project, provided that the maintainers on a mailing list agree to use Woof headers.

That said, contributions are welcome!

Support the Clojure(script) ecosystem

If you like Clojure(script), please consider supporting maintainers by donating to clojuriststogether.org.

License

© Bastien Guerry 2020-2021

Woof is released under the EPL 2.0 license.