Skip to content

Latest commit

 

History

History
228 lines (155 loc) · 6.85 KB

howto.md

File metadata and controls

228 lines (155 loc) · 6.85 KB
Raw

About Woof!

This website is an instance of Woof!, an application that tracks and exposes useful interactions on mailing lists.

Woof! can typically be used for software development mailing lists when these lists serve as channels for reporting bugs, submitting patches, proposing feature requests, sharing tips, etc.

Reports

Report types

Report Permission Specificity
bug Anyone Bug can have a version number as [BUG version]
patch Anyone Woof! stores and exposes the patch itself when possible
request Anyone Any request can be voted upon with +1 and -1
blog Anyone The body of the email is exposed in the RSS feeds
announcement Maintainers The body of the email is exposed in the RSS feeds
release Maintainers Requires a version number for the released changes
change Maintainers Requires a version number for the upcoming change

Adding a report

Adding a report to Woof! is done by using subject prefixes:

  • bug : [BUG] or [BUG x] where x is a version number
  • release : [RELEASE x] or [REL x] where x is a version number
  • change : [CHANGE x] where x is a future (not released) version number
  • patch : [PATCH] or [PATCH n/m] or an email with a diff or patch attachment
  • request : [FR] or one of [FP, RFC, RFE, TASK, POLL]
  • blog : [BLOG] or [TIP]
  • announcement : [ANNOUNCEMENT] or [ANN]

Report states

All report types can be in a combination of these states: (un)acked, (un)owned and (un)closed.

  • Acked means that someone took the next sensical action: e.g. for a bug, someone confirmed it; for a patch, someone reviewed it.
  • Owned means someone claimed to handle this report. You can own a report that has not been acked.
  • Closed means the report has been closed, either because it has been fixed (for a bug), canceled or done in any fashion.

Updating a report

Some words at the beginning of a line in the body of a reply to a report trigger an update of this report.

E.g. if a line in your reply to a bug report starts with Confirmed., the bug report will be updated as "Confirmed" in Woof!.

Here are the default "triggers", the terms you can use for trigger an update:

  • bug : Confirmed, Handled, Fixed or Canceled
  • blog : Canceled
  • patch : Approved, Reviewed, Handled, Applied or Canceled
  • request : Approved, Handled, Done, Closed or Canceled
  • announcement : Canceled
  • release : Canceled
  • change : Canceled

Note: These words (Confirmed, Approved, etc.) are case-sensitive and a punctuation mark among ;:,. is mandatory after each of them.

Updating the priority

You cannot set the priority of a report directly: it is computed based on whether the report is important and urgent.

But you can update a report as (un)important and/or (not-)urgent.

  • To set a report as important, use "Important" in a reply.
  • To set a report as unimportant, use "Unimportant" in a reply.
  • To set a report as urgent, use "Urgent" in a reply.
  • To set a report as not urgent, use "Not Urgent" in a reply.

Using multiple triggers

You can use multiple triggers in the same email. E.g. in a reply against a bug report:

Confirmed.
Urgent.
Important.

will mark the bug report as confirmed, and set it as important and urgent, giving it the highest priority.

Updating a report without replying to the mailing list

Sometimes it can be useful to create or update a report without notifying all the subscribers of the mailing list: maintainers can do this by writing directly to the Woof! inbox (i.e. :inbox-user in the config_example.edn file.)

Say for example that someone sends a feature request; after two years, you decide to cancel this feature request but don't want to notify the list. In this case, and provided you are a maintainer of this Woof! instance, you simply hit "reply" from your email client and add the Woof! monitored email in the To: field: the report will be unlisted from feature requests.

This also goes for updating reports: say someone forgot to add the "[BUG]" prefix for reporting a bug. As a maintainer, you can edit the subject of the email you received and resend it to the Woof! inbox, it will be store as a bug report.

Search

Woof! web interface allow users to search reports.

You can use abbreviations (f[rom], a[cked], o[wned], c[losed]) and combine search parameters:

Admins and maintainers

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
  • [Add|Remove] admin: [email protected] : Add or remove an admin
  • [Add|Remove] maintainer: [email protected] : Add or remove a maintainer
  • [Delete|Undelete]: [email protected] : Clean up past reports
  • [Ignore|Unignore]: [email protected] : Ignore future reports

Add, Remove and (Un)Delete/(Un)Ignore commands can accept several arguments: you can use Ignore: [email protected] [email protected] to ignore future messages from these two users.

Maintainers can perform three actions:

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