Bug, Patch, Request

The subject label determines a report's type. The three main labels are [BUG], [PATCH] and [FR/TODO/POLL] for feature requests; see report types for the full list.

BONE creates a patch report in two cases:

1. The subject starts with [PATCH], either directly or as Re: [PATCH] ... when the reply carries a .patch or .diff attachment (the v2/v3 reply workflow).
2. The email attaches a git format-patch file whose inner Subject: header starts with [PATCH].

A bare inline diff, a git diff > x.patch attached in a reply without re-labelling, or a quoted diff in a discussion stay regular replies. To track such a fix as a patch, attach a real git format-patch file or relabel the subject with [PATCH].

Attaching a patch to a [BUG] or [FR] email leaves the report's type unchanged; the patch is stored as metadata on the parent.

Updating reports

Updating reports is done via a BONE command, a case-sensitive keyword at the start of a line. For example, a reply to a bug starting with Confirmed. marks it acked; a reply to a patch starting with Applied. or Fixed. marks it closed; a reply to a request starting with Canceled marks it canceled.

BONE commands are followed by punctuation (. , ; : ? !), whitespace, or end of line. As an exception, Urgent and Important are stricter: a whitespace is not enough, they require punctuation or end of line, because the same words appear too often in ordinary prose.

There are two kinds of commands: triggers, which change the report state and annotations, which update their properties. Triggers never apply to the email that carries them, only to the closest parent report: for example, a Acked command in a new bug report does not confirm the bug. Annotations apply to the closest parent report too but can also apply to the report the email creates: for example, adding Urgent. in a new bug report increases its priority.

See the complete list of commands for the full registry.

Retracting your own updates

To retract a state you previously set with Acked., Owned., Closed., Urgent. or Important., reply with the matching "Not" command:

Not acked.
Not owned.
Not closed.
Not urgent.
Not important.

Each retraction applies only to your own earlier action. Maintainers have broader retraction rights, described in Undoing updates.

Setting a topic

A topic is a short string attached to a report. Set it from the subject in two ways:

• Inside the label: [BUG parser] sets the topic to "parser".
• As a colon prefix after the label: [BUG] parser: crash on empty input also sets the topic to "parser" -- the segment before the first colon after the closing bracket.

To change the topic on an existing report, reply with:

Topic: new-topic.

To remove it, reply with No topic..

Setting a deadline

To set a deadline on a report, reply with:

Deadline: 2026-03-10.

The value is an ISO date (yyyy-MM-dd) or a duration (2d, 3w, 1m, 1y) resolved relative to today. A trailing punctuation mark is optional. Deadlines appear in JSON exports, in Org output as a DEADLINE: line, and in notification emails.

To remove a deadline, reply with No deadline..

Setting an expiry date

A per-report expiry date schedules the automatic closing of a report.

To set an expiry, reply with one of:

Expiry: 2026-06-15.
Expiry: 30d.

Like Deadline:, the value is an ISO date or a duration. The expiry appears in JSON exports under :expiry, in Org output as an :EXPIRY: property, and in the HTML index as a tooltip on the date column.

To expire reports at their deadline, use :inactive-after :deadline in the source-level expiry rules (see report expiry).

To remove a per-report expiry, reply with No expiry..

Superseding a report

One report can replace another: a newer patch version, or a fresh bug report that captures the real issue.

From the old report's thread, you can write:

Superseded-by: <new-message-id@example.com>

From the new report's thread, you can write (in a reply, or in the opening mail of a new bug, patch or request):

Supersedes: <old-message-id@example.com>

A message-id takes one of three forms: <id@host>, the bare id@host, or the last path segment of an archive URL such as https://list.orgmode.org/orgmode/id@host/. Both reports must be of the same type: bug to bug, patch to patch, request to request.

To undo, reply with Not superseded-by: <new-message-id@example.com> from the closed report's thread, or with Not supersedes: <old-message-id@example.com> from the replacement's thread.

Supersession of patches

When a new patch report appears in a thread whose earlier open patch report shares the same base subject (ignoring Re: or Fwd: prefixes and [TAG] brackets), the new report automatically supersedes the previous one. This covers re-sent patches without explicit version numbers.

For example:

[PATCH] A new feature          : patch report (1)
  Re: [PATCH] A new feature    : patch report (2), supersedes (1)
    Re: [PATCH] A new feature  : patch report (3), supersedes (2)

Only the most recent patch (3) remains open.

The reply must itself qualify as a patch report -- either a Re: [PATCH] subject with an attached patch, or a git format-patch attachment. A plain Re: without a patch carries on as ordinary discussion.

Patches with an explicit version number ([PATCH v2]) follow a separate mechanism that matches on version and topic. See Patch series.

Resolving a bug or request with a patch

Replying to an open bug or request with a .patch or .diff attachment credits you as Acked and Owned on that parent, if the nearest parent is a bug or a request. (When you are the parent's own reporter, only Owned is credited, as you cannot Ack a report you sent.)

Closing that patch with Applied. or Fixed. then propagates the closure to the parent, with reason :resolved. Cancelling the patch retracts the implicit credit. Superseding it transfers Owned to the new author; Acked is historical and stays with whoever first confirmed the parent.

Marking a report as a duplicate

To mark a report as a duplicate of another, reply with:

Duplicate-of: <target-message-id@example.com>

Message-id forms and type constraints match Superseded-by: (see above). BONE closes the duplicate with reason :canceled and links it to the target. To undo, reply with Not duplicate-of: <target-message-id@example.com>.

Cross-referencing reports

To cross-reference another report, reply with:

Related-to: <other-message-id@example.com>

This annotation accepts any pair of reports, including closed ones, and uses the same message-id forms as Superseded-by:. Several Related-to: lines in one email post several links. To undo, reply with Not related-to: <other-message-id@example.com>.

Voting on requests

Requests ([POLL], [TODO] and their aliases) accept votes. Reply to the thread with one of:

• +1 or 1+ -- a positive vote.
• -1 or 1- -- a negative vote.
• +0, 0+, -0 or 0- -- an abstention.

Each voter is counted once per report; the first vote wins.

Announcements, releases, changes

A maintainer can post general announcements ([ANN]), share a release ([REL]), or announce an upcoming change ([CHG]) for a future release.

When a [REL] report carries a version in its subject tag ([REL v2.0]), it closes every open [CHG v2.0] report with reason :resolved and cross-links them to the release.

Events (ICS calendar support)

An announcement can carry a calendar event. When an [ANN] report contains an attached .ics file or inline VCALENDAR content, BONE stores the calendar data alongside the report. During export, such announcements feed dedicated event feeds:

• Individual .ics files in events/<mid-hash>/.
• Combined ICS calendars:
  • events/announcements.ics -- all announcements with events.
  • events/announcements-open.ics -- open only.
  • events/announcements-closed.ics -- closed only.
• events.json, events.org, events.xml -- open announcements with ICS content; events-closed.* list closed ones.

Use [ANN event] to set the topic to "event" for easier filtering, but any announcement with ICS content is included regardless of topic.

Acting as an update proxy

A maintainer can update a report on behalf of another user by writing directly to the BONE inbox with a -by line:

Acked-by: a-user@example.com
Owned-by: a-user@example.com
Closed-by: a-user@example.com

The Name <addr> form is also accepted:

Owned-by: A User <a-user@example.com>

Managing roles and permissions

Permissions follow three rules:

• Each source has exactly one lead maintainer.
• Any maintainer can promote another user to maintainer.
• Only the lead maintainer can demote a maintainer back to user.

To change roles, write to the BONE inbox:

Add maintainer: dev@example.com        (any maintainer)
Remove maintainer: dev@example.com     (lead maintainer only)

BONE also accepts the Display Name <addr> form:

Add maintainer: Dev User <dev@example.com>

State-changing actions (commands and role controls) must be sent through the source's public channel -- the mailing list or alias. Every instance of BONE running on the same source then sees the same state.

Undoing updates

A maintainer can undo any update with the same "Not" or "No" commands available to regular users:

Not acked.
Not owned.
Not closed.
Not urgent.
Not important.
No deadline.
No expiry.
No topic.
Not superseded-by: <new-message-id@example.com>
Not supersedes: <old-message-id@example.com>
Not duplicate-of: <target-message-id@example.com>
Not related-to: <other-message-id@example.com>

A regular user can retract only their own actions (see Retracting your own updates); a maintainer applies the same commands without that restriction.

Patch series

A patch series groups patches sharing a sequence marker (<n/m>). A cover letter (0/m) or a fresh 1/m patch from the same sender and topic automatically closes the previous series and starts a new one. This is how a version bump supersedes the previous run: [PATCH parser v2 0/3] closes the earlier v1 series.

Customising subject labels

The labels above are the built-in defaults. Override them globally or per source in config.edn through :labels. Only the types you list are affected; the others keep their defaults.

;; Global override (applies to all sources)
:labels {:bug     ["BUG" "DEFECT"]
         :request ["POLL" "FR" "TODO" "RFE"]}

;; Per-source override (inside a source map)
{:name "my-list"
 :labels {:announcement ["ANN" "NEWS"]}}

A per-source setting wins over the global :labels, which in turn wins over the built-in defaults.

Triggers and annotations

BONE distinguishes two kinds of commands:

• A trigger changes a report's state -- open/closed, acked, owned, superseded, duplicate. Triggers never apply to the mail that carries them, even when that mail opens a new thread. Examples: Closed., Acked., Owned-by:, Superseded-by:, Duplicate-of:.
• An annotation sets or unsets a property -- urgency, importance, topic, deadline, expiry, or a non-closing relation. When the carrying mail itself becomes a new report, the annotation applies to it; otherwise it targets the nearest report in the thread. Examples: Urgent., Important., Topic:, Deadline:, Supersedes:, Related-to:.

Two annotations are stricter on punctuation: Urgent and Important require punctuation or end of line, never whitespace (see priority commands).

Colon-prefixed commands -- Topic:, Deadline:, Expiry:, Acked-by:, Owned-by:, Closed-by:, Superseded-by:, Supersedes:, Duplicate-of:, Related-to: -- require at least one whitespace character between the colon and the value. Topic: parser is recognised; Topic:parser is silently ignored.

Status commands

A report carries a combination of three states:

:acked

someone took the next sensible action -- confirmed a bug, reviewed a patch, approved a request.

:owned

someone claimed ownership of the report.

:closed

the report is resolved, canceled, or expired.

The numeric form combines these three bits:

An acked, unowned and open report therefore has status 1+0+4 = 5.

Only bugs, patches and requests carry acked or owned. Announcements, releases and changes can still be marked urgent or important, and can still be closed.

Priority commands

Urgent and Important require punctuation (. , ; : ? !) or end of line. A bare space is rejected: words like "Important" appear too often in ordinary prose to be safe bareword annotations.

These two values combine into the numeric priority:

A report flagged both important and urgent has priority 1+2 = 3.

Multiple commands

You can use several keywords in the same email, one per line.

From: x@y.z
Date: Thu, 19 Mar 2026 16:45:00 +0100
Subject: Re: [BUG] Crash on startup

> Crash on startup with the new build.

Confirmed.
Urgent.
Important.

Propagation

Some updates ripple beyond the report they were sent to. BONE propagates them through the threading and series graphs:

• Closing a patch with Applied. or Fixed. also closes its parent bug or request, with reason :resolved. See Resolving a bug or request with a patch.
• Commands sent to the cover letter [PATCH 0/m] of a series apply to every patch in the series (except cross-references). See Cover letter commands.
• A reply that itself carries a new patch supersedes the previous patch report in the same thread. See Supersession of patches.
• A new patch-series version (matching topic) closes the previous series with reason :superseded. See Patch series.
• A [REL v2.0] release closes every open [CHG v2.0] report. See Announcements, releases, changes.

All commands

A command is a keyword sent in a public reply, by a user or a maintainer. In the "Permission" column, "setter or maintainer" denotes the user who previously set the attribute; a maintainer retains a full override in every case.

Triggers act on existing reports only. Annotations also apply to the carrying mail when that mail itself becomes a new report.

All controls

A control manages a role. Role controls must be sent through the source's public channel.

Exported pages and feeds

Running bb export all generates, for each source:

• HTML pages: index.html (reports table), stats.html (charts), docs.html (user docs).
• Full exports: all.json, all.org, all.xml.
• Per-type feeds: bugs.json, patches.xml, requests.org, etc.
• votes.json -- per-report vote details (see below).
• patches/ -- attached and inline patch files.
• text/<mid-hash>/ -- text/plain and text/x-log attachments (backtraces, log files).
• events/<mid-hash>/ -- .ics attachments from announcements; combined feeds at events/announcements{,-open,-closed}.ics aggregate VEVENT blocks for subscription.
• events.{json,org,xml} and events-closed.{json,org,xml} -- open/closed announcements carrying .ics or inline VCALENDAR content.

RSS feeds carry up to 50 items, most recent first. Export is incremental: only sources modified since the last export are regenerated. Use --force to rebuild everything, or bb export {json|rss|org|html|stats|text|events} to rebuild a single format.

Durations accept Nd, Nw, Nm, Ny (e.g. --closed-retention 1y keeps reports closed within the last 12 months).

Vote transparency

BONE stores each vote on a request as a separate entity recording its voter and its source email. Export produces a votes.json file per source so anyone can audit the results:

{
  "<11@test.org>": {
    "+1": [{"voter": "alice@example.org", "message-id": "<12@test.org>"}],
    "-1": [{"voter": "bob@example.org",   "message-id": "<13@test.org>"}],
    "0":  []
  }
}

BONE counts each voter once per report; the first vote wins. The per-report JSON still includes summary counts (votes, votes-up, votes-down, votes-null) for display, derived from these entities at export time.

Browsing BONE reports online

The exported HTML site lets you browse a source's reports and filter them through a minimal search syntax:

Durations are Nd (days), Nw (weeks), Nm (months). date: looks backward from today; deadline: and expired: look forward.

The gnaw CLI tool and Emacs clients

• gnaw lets you browse and filter BONE reports from the terminal.
• gnaw.el provides the same view as a standalone GNU Emacs tool.

Subscribing or changing preferences

Subscriptions are not managed by email. To subscribe, unsubscribe, or adjust filters (minimum priority, subject match, topic), ask the operator to edit config.edn. This is a deliberate trade-off: notifications are configured the same way as SMTP and the maintainer list, so the operator owns the full declaration of who receives what.

The bb notify task -- run by the operator from cron or a systemd timer -- builds and sends the digests; bb notify --dry-run prints them without sending. Cadence is the operator's choice; the task tracks no per-recipient interval.

Setting up an instance

The shortest valid configuration declares a single IMAP mailbox and one source:

{:mailboxes [{:name     "primary"
              :type     :imap
              :host     "imap.example.com"
              :port     993
              :ssl      true
              :user     "imap-login@example.com"
              :password "secret"
              :folder   "INBOX"}]

 :sources [{:name        "my-list"
            :list        "my-list.example.org"
            :maintainers ["lead@example.org"]}]}

:mailboxes is a vector: every mailbox is a map with a unique :name (used to key its watermark and prefix logs) and a :type of :imap or :maildir. The singleton :mailbox key from older releases is no longer accepted -- migrate to the vector form even if you only have one mailbox.

The :db, :logging and :ingest sections are optional. Defaults: :db {:path "data/bone-db"}, stderr-only logging at :info, and :ingest {:fetch {:limit 50}}. See config.edn.example for the full annotated reference.

To keep IMAP/SMTP credentials out of config.edn itself, either:

:password-file "/etc/bone/imap.pwd"   ; trimmed contents read at startup
:password      #bone/env "BONE_IMAP_PWD"  ; resolved from the environment

Both forms fail loudly at startup if the file or env var is missing, rather than silently using a nil password. The file form pairs well with systemd's LoadCredential=imap-pwd:/etc/bone/imap.pwd (the secret is mounted under $CREDENTIALS_DIRECTORY) and with Docker secrets (/run/secrets/imap-pwd). :password and :password-file are mutually exclusive in the same map.

BONE also reads Maildir folders. Point :path at the parent directory containing cur/, new/ and tmp/, and use :folder to select the subfolder. Set :folder "" when the Maildir at :path already holds cur/, new/ and tmp/ directly. A Maildir source in watch mode uses filesystem events rather than polling.

{:mailboxes [{:name   "local"
              :type   :maildir
              :path   "/home/me/Mail"
              :folder "INBOX"}]
 :sources [{:name "my-list" :list "my-list.example.org"}]}

{:mailboxes [{:name     "upstream"
              :type     :imap
              :host     "imap.example.com" :port 993 :ssl true
              :user     "me@example.com"   :password "secret"}
             {:name     "forge"
              :type     :maildir
              :path     "/home/me/Mail/forge"
              :folder   ""}]
 :sources  [{:name "my-project" :list "my-project.example.org"}
            {:name "issues"     :to   "issues@example.com"}]}

{:mailboxes [{:name "upstream" :type :imap :host "..." :user "..." :password "..."}
             {:name "forge"
              :type :maildir
              :path "/home/me/Mail/forge"
              :folder ""
              ;; Only fetch the last 7 days from the forge bridge,
              ;; while the upstream mailbox keeps the global default.
              :ingest {:fetch {:since "7d"}}}]
 :ingest    {:fetch {:limit 200}}
 :sources   [{:name "..." :list "..."}]}

Trust model and MTA requirements

BONE identifies every actor -- author, maintainer, voter, command issuer -- by the From: header of incoming mail. BONE does not verify DKIM, SPF or DMARC itself. It relies on the upstream MTA to filter forged mail before it reaches the Maildir or IMAP folder BONE watches.

This has practical consequences:

• Trivial actions (creating a report, Acked., Owned., votes, closing a thread) treat the From: address as authoritative. An attacker who successfully delivers a mail with a forged From: can vandalise a report. Damage is bounded: a maintainer can always retract by command, and the audit trail keeps the offending message-id.
• Sensitive actions are stronger by design: Add maintainer / Remove maintainer / Set lead require the issuer to already be a maintainer (or the lead); the lead maintainer cannot be removed. Announcements and releases require maintainer status. But those checks still rely on From:, so they are only as strong as the upstream filtering.

Recommended deployment posture:

• Run BONE behind an MTA that injects Authentication-Results for every delivered mail (Postfix + OpenDKIM/OpenDMARC, or any mail provider that supplies them).
• Configure the MTA to reject -- not just tag -- messages that fail DMARC for domains with p=reject or p=quarantine policies. The default behaviour of most MTAs is to honour the sender's policy, which means domains publishing p=none will still let spoofs through.
• If your sources are public mailing lists (Mailman, sourcehut, etc.), be aware that list mail typically arrives with dmarc=fail even when legitimate, because the list rewrites headers. Bone cannot distinguish a legitimate Gmail-via-list mail from a spoofed one without reading Authentication-Results itself -- which it does not, for now.
• For a personal Maildir watched by a single user, this whole section is mostly informative: you are the only writer with practical delivery, and the attack surface reduces to whatever can reach your inbox -- which is already your spam problem.

If your deployment exposes BONE to a public list where you cannot trust the upstream filtering, treat maintainer changes and announcements as advisory and audit the source Message-Id before acting on them.

Monitoring your local mail

BONE can run on a single machine to watch your own mail. In that mode:

• The mail source is a Maildir (see the example above). Watch mode reacts to filesystem events -- no polling, no IMAP credentials.
• SMTP notifications are usually unnecessary: you already read the mailbox BONE watches. Either omit :notifications or set :enabled false.
• One source is enough. Match on :to or :list depending on which header your local MDA stamps.

To keep BONE in the background, install the user-level systemd unit from docs/deploy/bone.service (see Running BONE in production).

Source types and matching

A source has exactly one type key, which determines how BONE matches incoming emails:

• :list -- matches the List-Id header (bare identifier, e.g. "my-list.example.org"). Detected as list mail when List-Id or X-BeenThere is present.
• :alias -- matches X-Original-To, Envelope-To, X-Envelope-To, or Delivered-To. Detected as alias mail when the original recipient differs from To=/=Cc, or when multiple distinct Delivered-To values are present.
• :to -- matches Delivered-To. For a dedicated mailbox where all emails are delivered directly.

Emails that match no source are discarded at ingestion.

Source options

Source periods

When a source's vocabulary or maintainer list has evolved over time, declare the history inline with :periods -- a vector of time-windowed overrides. Each entry may declare :start / :end (ISO yyyy-MM-dd) plus any of :maintainers, :commands, :command-syntax, :labels, :restricted-types. Fields omitted in a period inherit from the source level (the current state).

{:name "orgmode"
 :list "emacs-orgmode@gnu.org"
 :maintainers ["current-lead@example.org"]    ;; default + current era
 :periods
 [{:end "2020-01-01"
   :maintainers ["old-lead@example.org"]
   :commands    {:closed {:words ["Done" "Fixed"]}}}
  {:start "2020-01-01" :end "2024-01-01"
   :maintainers ["mid-lead@example.org" "co@example.org"]}
  {:start "2024-01-01"                         ;; last era, no :end
   :maintainers ["current-lead@example.org"]}]}

Rules:

• Periods must be contiguous: :end of era N equals :start of era N+1.
• Only the first period may omit :start (unbounded past).
• Only the last period may omit :end (still active).
• bb test-config validates the periods and rejects gaps or overlaps.
• At each boundary, sync recomputes maintainer tenure: it adds declared maintainers missing at the boundary, and closes previously- active maintainers absent from the declared list at the boundary's :start.
• Add/Remove maintainer: controls in emails continue to mutate tenures in real time between boundaries.
• Sync is idempotent: re-running on an existing DB never duplicates tenures and does not reinstate maintainers closed by a past mail control. To replay from scratch, run clj -M:run -- --fresh.

Report expiry

BONE can automatically close any report type when its age and state match configured rules. It sets the close reason to "expired".

Each entry under :expiry maps a report type keyword to a rule map:

All rules are conjunctive: a report expires only when all conditions are met. Only :inactive-after is required; the others are optional filters.

The :max-status value uses an activity score that only counts acked and owned (since expiry candidates are always open reports):

:expiry {:announcement {:inactive-after "30d"}
         :release      {:inactive-after "6w"}
         :change       {:inactive-after "3m"}
         :bug          {:inactive-after "1000d"
                        :max-status 0      ;; only open, unacked, unowned
                        :max-priority 0}   ;; only non-urgent, non-important
         :request      {:inactive-after "1000d"
                        :max-status 0}}

Can be set globally or per source (per-source wins).

Tuning ingestion

:ingest {:fetch    {:limit 50}    ;; or {:since "30d"} or {:start "…" :end "…"}
         :max-size 1048576}       ;; skip emails > 1 MB (optional)

• :fetch -- first-run fetch window (no watermark yet). Exactly one of three disjoint map shapes (no key mixing, empty map rejected); default is {:limit 50}:

  Config form	CLI shortcut	Meaning
  {:limit N}	--fetch 50	Latest N messages (positive integer)
  {:since "Nd"}	--fetch 30d	Relative duration from now (Nd, Nw, Nm, Ny)
  {:start "yyyy-MM-dd" :end "..."}	--fetch 2020-01-01	Absolute half-open window [start, end); both keys optional, at least one required

• :max-size -- skip emails larger than N bytes. No limit by default.

BONE extracts the text content of .patch, .diff, .ics, text/plain and text/x-log attachments and stores it in the database. It skips attachments larger than 1 MB (1,048,576 characters) with a warning, keeping only metadata (filename, size, content-type). Override the limit with :max-attachment-size in :ingest.

Notifications (SMTP)

:notifications
{:enabled true
 :smtp {:host     "smtp.example.com"
        :port     587
        :tls      true
        :user     "notify@example.com"
        :password "secret"
        :from     "bone@example.com"
        :reply-to "lead@example.com"}   ;; optional
 :admin-bcc "ops@example.com"           ;; optional; string or vector
 :subscribers
 {"a@example.org"
  [{:source "my-list"}]
  "b@example.org"
  [{:source "my-list" :min-priority 2}
   {:source "another-list" :topic "release"}]}}

Each key under :subscribers is a recipient's address. The associated vector lists their subscriptions, one per source -- a recipient on three sources receives three separate emails per bb notify run.

:admin-bcc adds a hidden carbon-copy on every subscriber digest. A single address as a string, or a vector of addresses. Useful to audit deliverability and to catch bounces. The BCC field is not visible to the other recipients (standard SMTP semantics).

Optional per-subscription filters:

:min-priority and :min-status filter only the "unacked & unowned" section -- the highest-volume one. Reports you own (with or without deadline) always appear regardless of priority or status.

bb notify tracks no per-recipient cadence: it sends every time it is invoked. Schedule it from cron or a systemd timer. bb test-config verifies that every :source named under :subscribers matches an existing source :name.

A small state file, data/.last-notify-failures.edn, records the last successful send per (subscriber, source) so the same failed-command entries are not re-mailed at every run. Delete the file to replay all current failures on the next invocation.

BONE keeps command failures on file for the subscriber digest and for manual inspection via bb maintenance --failures. BONE does not mail the author of a failing command directly: an unsubscribed user who typed Superseded-by: with a typo learns of the failure only if they are themselves on the subscriber list. Maintainers see all failures with :audience :maintainers in their digest.

Logging

:logging {:file     "logs/bone.log"
          :level    :warn
          :max-size "10MB"
          :backlog  5
          :email    {:to    "ops@example.com"
                     :level :error}}

Log file rotation is automatic. Email alerts require SMTP to be configured.

Running BONE in production

BONE can be deployed in two modes.

Watch mode under systemd

The daemon stays up, reacts to IMAP IDLE or Maildir filesystem events, and reconnects on failure. A ready-to-edit unit file lives in docs/deploy/bone.service. Install it to /etc/systemd/system/bone.service (root) or ~/.config/systemd/user/ (user), then run systemctl [--user] daemon-reload && systemctl [--user] enable --now bone.

Batch mode under cron

clj -M:run is a one-shot: it connects, fetches new mail since the watermark, digests, expires, and exits. Chain bb export and bb notify after it. An example crontab lives in docs/deploy/crontab.example.

Either mode can be backed by an uberjar to avoid the Clojure startup cost; see Quick start in README.org.

Customising commands

Command keywords can be customised globally or per source.

:commands {:closed   {:words ["Canceled" "Fixed" "Wontfix"]}
           :acked    {:words ["Approved" "LGTM"]
                      :scope :maintainer}               ;; Restrict to maintainers
           :deadline {:report-types
                      #{:bug :patch :request :change}}  ;; Widen to changes
           :unclosed {:scope :setter-or-maintainer}}    ;; Override scope only

:command-syntax :strict

Maintenance

The bb maintenance task reports and prunes orphan emails. Run it while the daemon is stopped.

bb maintenance                  # dry run, show orphan counts
bb maintenance --delete         # actually delete orphan emails
bb maintenance --verbose        # list individual orphan message-ids
bb maintenance --failures       # list recent command failures recorded
                                # for maintainers (denied actions, bad
                                # syntax, etc.)
bb maintenance --retention 6m   # override default orphan retention
                                # (90 days). Accepts "30d", "6m", "1y"
                                # or an ISO date.
bb maintenance -n my-source     # scope to a single source

An orphan email is one that no report references and that no maintainer has sent.

Rebuilding history

A source's historical evolution -- vocabulary, syntax, maintainer list -- is declared inline through :periods entries. See Source periods for the full format and rules. At startup, BONE materialises the tenure history by syncing at each period boundary, and resolves the effective config for every email from its date.

To replay from scratch after editing periods (or any config change you want reflected retroactively), wipe the DB:

clj -M:run -- --fresh   # interactive confirm, then full replay

bb test-config validates :periods on each source: contiguity, ISO date format, :start strictly before :end.

Patch review cycle

A contributor submits a patch series:

From: carol@dev.org
Subject: [PATCH parser v1 0/2] Refactor tokenizer

Cover letter: this series splits the tokenizer into two passes.

From: carol@dev.org
Subject: [PATCH parser v1 1/2] Extract lexer phase

<inline patch>

From: carol@dev.org
Subject: [PATCH parser v1 2/2] Add second pass

<inline patch>

BONE creates a patch series (cover + 2 patches). The maintainer reviews and asks for changes:

From: eve@project.org
Subject: Re: [PATCH parser v1 1/2] Extract lexer phase

> <inline patch>

The naming is confusing, can you rename foo to bar?

Carol resubmits as v2:

From: carol@dev.org
Subject: [PATCH parser v2 0/2] Refactor tokenizer

v2: renamed foo to bar as requested.

BONE automatically closes the v1 series and opens a v2 series. The maintainer applies:

From: eve@project.org
Subject: Re: [PATCH parser v2 0/2] Refactor tokenizer

Applied, thanks!

The v2 series is now closed (resolved).

Maintainer triage

A bug comes in with no response for a while. The maintainer triages by replying to the list:

From: eve@project.org
To: bugs-list@project.org
Subject: Re: [BUG] Crash on startup

Confirmed.
Owned.
Urgent.

Later, the fix lands:

From: eve@project.org
To: bugs-list@project.org
Subject: Re: [BUG] Crash on startup

Fixed in commit abc123, thanks for reporting!

Role management

Any maintainer adds a new maintainer (via the list):

From: eve@project.org
To: bugs-list@project.org
Subject: Role update

Add maintainer: newdev@project.org

Only the lead maintainer can Remove maintainer:.

Automatic expiry and override

With this config:

:expiry {:bug {:inactive-after "90d" :max-status 0}}

A bug whose last email is 91 days old, still unacked and unowned, is automatically closed with reason "expired" on the next expiry run.

To keep a legitimately old bug open, a maintainer marks it owned (which lifts it above :max-status 0):

From: eve@project.org
To: bugs-list@project.org
Subject: Re: [BUG] Old encoding issue

This is still relevant, keeping it open.
No expiry.
Owned.

Marking the bug owned takes its status above :max-status 0, so the expiry rule no longer applies. No expiry. clears any per-report expiry date previously set.