# Public board (roadmap, voting, changelog)

The public board is the Canny-style, public-facing part of Usero. Turn it on and you get a page anyone can reach where they submit
feature requests, upvote what others posted, and follow a roadmap of what you are building. You publish a changelog there to
announce what shipped.

The board is separate from the rest of Usero. A board post is not the input that becomes an AI-authored pull request today; the PR
pipeline runs off feedback from the widget, Slack, forms, GitHub issues, the API, and notes left on changelog entries. Treat the
board as your public roadmap, not as the source of truth for what to build.

## What it does

- **Public submissions.** Anyone reaches `usero.io/b/<slug>/submit`, writes a request (a title and optional description, with an
  optional category and email), and it appears on the board. No account required.
- **Voting with no signup.** Visitors upvote any post. Votes are deduped per browser (a long-lived `__portal_voter` cookie), so a
  count reflects distinct people rather than repeat clicks. Clicking the upvote again removes the vote.
- **Comments, with official replies.** Each post has a comment thread anyone can join. A reply from your team is marked as
  official so it stands out.
- **A roadmap.** You move each post through statuses you control. The ones you flag as roadmap render as the public columns at
  `/roadmap`.
- **A changelog.** Announce what shipped at `/changelog`. Entries are authored by you, not auto-generated.
- **Your own domain (Pro and Team).** The board lives at `usero.io/b/<slug>` by default; paid tiers let you point a custom domain
  at it.

## Enable the board

1. Open your project and go to the public board settings.
2. Toggle the board on. Usero generates a board slug from your project name (you can change it; it must be unique). Your board is
   now live at `usero.io/b/<slug>`.
3. On first enable, Usero seeds a default set of statuses and categories (below) so the board works immediately. You can edit them
   afterwards.

That is the whole setup for the hosted URL. Pointing a custom domain at the board is a separate step covered below.

## Statuses and the roadmap

Statuses are how you run the board. Each post sits in exactly one status, and you move it as work progresses. The seeded defaults
are:

| Status       | On the roadmap? | Meaning                 |
| ------------ | --------------- | ----------------------- |
| Open         | No              | New, not yet triaged    |
| Under Review | No              | You are considering it  |
| Planned      | Yes             | Committed, not started  |
| In Progress  | Yes             | Being built now         |
| Complete     | Yes (done)      | Shipped                 |
| Closed       | No              | Declined or a duplicate |

A status flagged as a roadmap status appears as a column on the public `/roadmap` view. By default that is Planned, In Progress,
and Complete, which gives a visitor the three-column "what is coming" picture they expect. You can add a status, rename one,
delete one, and change a post's status from the board settings.

Categories (Feature Request, Bug Report, Improvement, and so on) are a separate axis for tagging what a post is about. They are
also seeded on first enable and fully editable.

## Submissions, votes, and comments

- **Submitting.** The submit page asks for a title (5 to 200 characters), an optional description, an optional category, and an
  optional email. As the visitor types a title, the page shows similar existing posts so they can upvote instead of filing a
  duplicate.
- **Voting.** One click to upvote, one to remove it. The per-browser cookie is the dedup key, so the count is a reasonable proxy
  for distinct interested people. It is not login-gated, by design: the lower the bar, the more honest the count.
- **Comments.** Anyone can comment on a post. Your team's replies are marked official so users can tell an answer from the product
  team apart from community chatter. Use this to answer "why not" once, in public.

## Changelog

The changelog at `/changelog` is where you announce shipped work. Entries have a type (feature, improvement, fix, or announcement)
and are published by your team from the changelog admin in your project. Marking a post Complete does **not** automatically create
a changelog entry; the two are separate so you control exactly what gets announced and how it is worded.

Published entries also feed the [What's new tab in the feedback widget](/docs/widget#whats-new-changelog-in-the-widget), so users
can read them in your app without visiting the board.

### Reactions and notes on entries

Every published entry collects engagement, with no setup:

- **Reactions.** Each entry (on the changelog index and on its own page) shows a three-way reaction row: Great, Okay, Not for me.
  Reacting is anonymous and one click, deduped per browser; clicking again changes or withdraws the reaction. Zero counts are
  hidden on the public page.
- **Written notes.** Under the reactions on the entry page is a note box with optional email and name fields. A submitted note
  arrives in your feedback inbox as an item with source **Changelog**, linked to the entry it was left on. From there it behaves
  like any other feedback: it clusters with related reports and can go to an [AI-drafted pull request](/docs/integrations/github).
  The reader sees a confirmation saying the note went to your inbox, and if they left an email, replies and
  [requester notifications](#telling-the-people-who-asked) can reach them.
- **Engagement on the admin page.** The changelog admin shows a per-entry line with reaction counts by sentiment and the number of
  notes the entry sent to the inbox.

Drafts and unpublished entries collect nothing.

### Drafting from shipped pull requests

If your project has a connected GitHub repo, the changelog admin shows every merged Usero pull request that has not been announced
yet. Tick the ones you want, click **Draft changelog entry**, and Usero writes a draft grouped by type, with each change traced
back to the request that caused it. The draft is unpublished, so you edit the wording before anyone sees it.

Entry bodies are markdown. Headings, bullets, bold, links, inline code, and tables all render on the public entry page. Raw HTML
in the body is shown as text rather than markup, and link URLs are limited to `http`, `https` and `mailto`.

### Telling the people who asked

When you publish an entry, Usero emails the users whose feedback led to the work. It follows the chain the data already has: entry
→ the merged pull requests linked to it → the feedback that caused each one → the email on that feedback.

- **You see the list before you send.** Each draft in the changelog admin shows how many distinct people publishing would email
  and a sample of the addresses. The publish button reads **Publish & notify N**, and asks for a confirm.
- **One email per person, not per request.** Someone who filed three of the shipped items gets a single email listing all three,
  quoting their own words back to them, with a link to the public entry.
- **Nobody is emailed twice.** Two guards run: the entry itself is stamped once its announcement goes out, so unpublishing and
  republishing does not re-send, and each piece of feedback is stamped once it has been announced, so a later entry that links the
  same feedback skips that person.
- **Requesters who left no email address are skipped.** Anonymous feedback has nobody to write to, so it is not counted in the
  preview.
- **Recipients can unsubscribe.** Every email carries an unsubscribe link, and an unsubscribed address is never written to again
  from any Usero notification.

**Turning it off.** Requester emails share the "notify submitters" opt-in in your project settings with the "your feedback was
resolved" email, so one switch controls whether Usero may write to your end users at all. With it off, publishing is silent and
the changelog admin says so on any draft that has requesters behind it.

Replies go to your team. Set a reply-to address in project settings, or Usero uses the account owner's email.

### Email subscriptions

Anyone can follow your changelog by email, not just the people whose requests shipped. The public changelog page shows a subscribe
field (when the "notify submitters" opt-in above is on; with it off, the form is hidden so there is never a subscribe button that
goes nowhere).

- **Confirmation first.** Entering an email sends a confirmation link. Only confirmed addresses are subscribed, so a typo or a
  prank never signs someone up. The page shows the same "check your inbox" message whether or not the address was already
  subscribed, so the form cannot be used to probe who is on the list.
- **What subscribers receive.** Each published entry, as one email: the title, the summary, and a link to the entry on your
  changelog. Subscribers whose own feedback shipped in the entry are deduped out and get the personal requester email instead.
- **The counts are visible before you publish.** The publish confirmation shows requesters and subscribers separately, and the
  button totals them: **Publish & notify N**.
- **One-click unsubscribe.** Every subscriber email has an unsubscribe link that works in one click and offers resubscribe in case
  it was a misfire. Unsubscribed addresses are never written to again, and resubscribing requires a fresh confirmation.

### Weekly digest

Subscriber emails are a cadence choice on the changelog admin page: **on every publish** (the default, described above) or **as a
weekly digest**, one release notes email bundling the week's published entries on the day you pick. Never both, so switching
cadence can never double-email anyone. Requester emails are unaffected: people whose own feedback shipped still get the personal
email at publish time.

- **A draft lands first.** The evening before the send day, the project owner receives the digest exactly as subscribers will see
  it, with the recipient count and a one-click skip link. Skipping needs no login and can be undone until the send hour.
- **Empty weeks send nothing.** No published entries, or no confirmed subscribers, means no draft and no digest. The admin page
  says so instead of going quiet.
- **The state lives in the product, not your inbox.** The changelog admin page always shows the next digest (send day, entries
  queued so far, subscriber count, when the draft goes out) and the last outcome: sent to N, skipped, or nothing to publish.
- A digest that could not send within 48 hours of its scheduled time is dropped, never sent late.

### RSS feed

Every board publishes its changelog as RSS 2.0 at `/b/<slug>/changelog/rss.xml` (or the same path on your custom domain). There is
an RSS button on the changelog page. The feed carries the 50 most recent published entries, newest first, with the title,
permalink, publish date, entry type as the category, the author, and the full rendered body. Nothing is gated: readers, Slack RSS
apps, and Zapier can subscribe without an account.

## Custom domain (Pro and Team)

On the Pro and Team plans you can serve the board from your own domain instead of `usero.io/b/<slug>`:

1. In the project settings, open the custom domain panel and enter the hostname you want (for example `feedback.yourapp.com`).
2. Usero gives you a DNS record to add at your registrar. Add it, then return and let Usero verify it.
3. Once the hostname is verified, your board is reachable on your domain. The board must be enabled and have a slug for the domain
   to resolve to it.

The custom domain is gated to the paid tiers. The free board uses the `usero.io` URL.

## Where the board fits (and where it does not)

The board is the public roadmap. It is the right tool for showing users their request is logged, letting them vote, and closing
the loop with a changelog. It is the wrong tool for deciding what to build on its own: most users never post on a board, so the
vote count over-weights the vocal minority. Read it as one input among several, and get the quiet majority from the widget,
support, and reaching out to users directly.

Board posts are also **not** connected to the AI-PR pipeline. Feedback that clusters and can open a GitHub pull request comes from
the widget, Slack, forms, GitHub issues, the API, and [notes on changelog entries](#reactions-and-notes-on-entries), not from
board posts. See [feedback clustering](/docs/clustering) and the [GitHub integration](/docs/integrations/github) for that path.

## Next

- [Feedback clustering](/docs/clustering)
- [GitHub integration (AI pull requests)](/docs/integrations/github)
- [Integrations overview](/docs/integrations)