In 2025, I want to make Woof more stable. I need to rethink the architecture to better articulate some processes.
- Decouple the storage of emails from the storage of information derived from them.
- Decouple the responsibility for storing emails from the responsibility for processing the information derived from them.
- Decouple the process of storing data from the process of exposing it to a separate frontend.
The idea is to have a separate process for storing emails, then a job for processing either all of them at once (when initializing Woof!) or the only those who have not yet been processed (when running as a cron job, for example), then a classical backend/frontend to expose data and display them.
We will stick to the idea that all commands should happen by email: no interaction will be enabled via the frontend.
When plugged to a mailbox subscribed to mailing lists, Woof! captures some of the emails sent to these lists (bug reports, patches, feature requests, etc.) and expose them on a webpage.
If you love emails and mailing lists and use them for free software development, you may consider giving Woof! a try: it can serve both as a replacement for traditional issue trackers and as a kind of personal information manager, e.g. tracking patches you send to various mailing lists.
Woof! has been developed based on years of relying on the Org mailing list for Emacs Org-mode development: I hope it can be useful to other projects too.
CAVEAT: Woof! is still in alpha, things can move.
See this howto for basic instructions on how to use Woof!
See tracker.orgmode.org for an example instance tracking the Org Mode mailing list.
Developing software by discussing on public mailing lists and sharing patches by email works fine.
At some point, you may need to track bug reports, patches, etc.
If you are using sourcehut.org, perhaps you will set up a new tracker for your project. Or if your software is part of the GNU project, perhaps you will set up debbugs for your package. But these trackers create new communication channels, new “databases” that you will have to maintain—and they are probably overkill for your needs.
This is where Woof! comes in handy as a way to monitor mailing lists.
You plug Woof! into your mailbox, it monitors emails sent to mailing lists this mailbox is subscribed to and it extracts and exposes useful information: bug reports, patches, changes, announcements, etc.
Woof! is not a full-fledged project management tool: e.g. it does not allow someone to assign tasks to someone else, to close reports, etc. If you really need such tools, Woof! is not a good candidate.
- Read only: Woof! is not a database of issues you need to maintain. Useful information is extracted from upstream email interactions, emails are the sole source of truth. So Woof! is read only: there is no login, no way to update stuff from the website.
- Decentralized: Since Woof! is based on mailboxes and only reflects upstream interactions, you can have several Woof! instances for the same mailing lists: each instance will reflect what is of interest for the person who deployed it.
- Minimalistic conventions: Woof! tries to rely on minimalistic and realistic conventions for subject prefixes (e.g. [BUG]) and updates “triggers” (e.g. “Confirmed.”).
- Configurable: Woof! tries to be highly configurable.
- Track various report types: bugs, patches, requests, etc.
- Support tracking multiple lists
- Expose reports as
rss,md,jsonororg - Expose raw downloadable patches when possible
- Support HTML and plain text emails
- Track related reports and allow to list them
- Track votes on requests (e.g.
[POLL]) - Allow complex searches
- Support theming
- Support i18n
There is no roadmap as I develop Woof! in my spare time, but here is a list of ideas for future versions.
- An Emacs tool to keep track of various Woof! instances
- Implement notifications
- Implement the overview page
- Separate woof-server/monitor from woof-web
- Enhance the hero header
- Expose data through GraphQL
- Add pagination
- Add “events” report type
- Allow individual notifications based on subject matches
- Use integrant more consistently (to stop)
- Add webhook
You will need a mailbox accessible via IMAP that Woof! will monitor.
This mailbox must receive mails sent to the mailing lists Woof! will monitor and must also be able to send emails.
See the environment variables in config_example.edn for setting the email information.
Woof! requires Clojure and Java.
You can install clojure with ~$ apt install clojure or see this guide.
You can install Java with ~$ apt install default-jre or refer to your
distribution instructions.
You need to copy config_example.edn as config.edn and to set
environment variables: see config_example.edn for the list.
config_example.edn also contains other configuration parameters that
you need to set. You can also refer to src/bzg/config.clj which
contains other configuration defaults.
Once you are done configuring Woof!, you can check your configuration with:
~$ clj -M:test
Run with:
~$ clj -M:run
Build and deploy with:
~$ clj -M:uberdeps ~$ java --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED -cp target/woof.jar clojure.main -m bzg.init
Run with:
~$ lein run
Build and deploy with:
~$ lein uberjar ~$ java --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED -jar target/woof.jar
Contributions are welcome! See CONTRIBUTING.md.
Suggested contributions:
- Write a new HTML theme
- Support new languages
- Enhance documentation
- Enhance performance and accessibility
- Add tests
- Report bugs
If you like Clojure(script), please consider supporting maintainers by donating to clojuriststogether.org.
© Bastien Guerry 2020-2025.
Woof is released under the EPL 2.0 license.
