NOTE: Do not deploy this version as it is still a work in progress.

#What is Woof! and how to use it?

Woof! monitors updates sent to a mailbox and exposes them on the web. Typically, this mailbox is subscribed to a mailing list with a public online archive so that Woof! reports can link to it.

Woof! tries to be a good companion for free software maintainers who work with mailing lists by allowing them to focus on bugs and patches. It also aims at making life easier for users by pointing at important news such as upcoming changes.

Woof! does not change the way maintainers use a mailing list for the development of their projects: with a minimalistic set of conventions, Woof! will extract what's important for everyone.

#Triggering a report

Woof! watches for triggers at the beginning of the subject line:

• [ANN] : An annoucement
• [BUG] : A bug report
• [HELP] : A help request

It also watches for patches:

• [PATCH] : A single patch
• [PATCH n/m] : A patch in a series
• A multipart mail with a text/x-diff or text/x-patch MIME part

Some triggers are special:

• [CHANGE x] : Announce a change in the release x
• [RELEASE x] : Announce the release x

The x part is mandatory for changes and releases and it should not contain any whitespace.

Announcing a release x moves changes for x from the Upcoming changes section to the Latest released changes one. Canceling a release moves the changes back to the Upcoming changes section.

Note that the [...] is case-sensitive.

#Updating a report

After a bug, patch, announcement, change, release or help request has been monitored, replies to the original mail can trigger actions.

Actions are declared at the beginning of a line in the reply.

For bugs:

• Confirmed. : Confirm a bug.
• Fixed. : Mark a bug as fixed.

For patches:

• Approved. : Approve a patch.
• Applied. : Mark a patch as applied.

For help requests:

• Handled. : Mark a request as currently handled.
• Done. : Mark a task of helping as done.

For bugs, patches, requests, announcements, changes and releases, you can also cancel them:

• Canceled. : Mark the bug, patch, request, announcement, change or release as canceled.

Note: A punctuation mark among ;:,. is mandatory for these reports and action words (Confirmed, Approved, etc.) are all case-sensitive.

#Notifications

Users receive a mail notification when their original reports are detected (new bug, new request, etc.) and when these reports receive an important update (the bug get fixed, the request get handled, etc.)

Every user can turn notifications on or off by writing to the Woof! mailbox with this command at the beginning of a line:

• Notifications: false : To turn notifications off
• Notifications: true : To turn notifications on

Admins can turn notifications globally on and off with

• Global notifications: [true|false]

#Admins

Each Woof! instance comes with a default admin.

Admins can update the main configuration:

• Global notifications: [true|false] : Enable/disable mail notifications globally
• Maintenance: [true|false] : Put the website in maintenance mode
• Set theme: my_theme : Use my_theme for the interface
• [Add|Remove] feature: feature : Add or remove a feature
• [Add|Remove] export: format : Add or remove an export format

In these actions:

• feature can be bug, announcement, request, change, release or mail.
• format can be rss, json, org or md.

They can also add or remove admins and maintainers:

• [Add|Remove] admin: woof@woof.io : Add or remove an admin
• [Add|Remove] maintainer: woof@woof.io : Add or remove a maintainer

Finally, admins can also delete past reports and ignore future mails:

• [Delete|Undelete]: woof@woof.io
• [Ignore|Unignore]: woof@woof.io

Remember: deletion is for cleaning up past reports, ignoring is about future emails. When plugging Woof! to a mailing list, first consider moderating users instead of ignoring them.

Add/Remove commands and (Un)Delete/(Un)Ignore commands accept several arguments: you can use Add feature: bug top to add both the "bug" and "top" features, or Ignore: user1@woof.io user2@woof.io to ignore future messages from these users.

#Maintainers

Maintainers can perform three actions:

• Add maintainer: woof@woof.io
• Delete: woof@woof.io
• Ignore: woof@woof.io

When contributors are promoted as maintainers, they receive a notification by email.

Note that maintainers cannot remove admins or other maintainers and they cannot undelete mails or unignore contributors.

#Sending multiple commands

One can send several commands in a mail, with each command starting at the beginning of a line. For example, an email with:

Set theme: my_theme
Add maintainer: my@friend.io myother@friend.io
Ignore: my@enemy.io

will set the theme "my_theme", add "my@friend.io" and "myother@friend.io" as maintainers and ignore future reports by "my@enemy.io".

#Woof without a mailing list

Woof! can monitor a mailbox that is not subscribed to a public list. In that case, the webpage exposes reports as texts with no links. But you can check reports by using their json export: it will give you the Message-Id of each report, allowing to find the corresponding email.