chadtmiller.com/knotless

Switch repository

Loading…

What changes

Watching a repository. An account can choose what it hears of a repository: all it does (pulls and issues opened, comments, releases), its releases alone, or nothing (ignore). participating, the default, forgets the choice. An ignored repository is heard of no more, but for a review asked of the account.

Subscribing to or muting a pull or issue. subscribed hears of every comment on one the account has no part in; muted hears nothing of it, mentions included, but a review asked of it.

Kept by the appview, for that account alone. dev.knotless.putSubscription and dev.knotless.listSubscriptions keep each choice in a table of the index kept across rebuilds, as preferences are, not in a record: it is how one reader wants its notifications read. A choice counts from when it is made. A repository is kept by owner and key, so a rename keeps it. An account keeps 1000 at most.

Two new reasons. listNotifications gives subscribed (a comment on a thread it subscribed to) and watching (a pull, issue, comment or release on a repository it watches). Each is heard of only when no other reason would give it, so a record is still heard of once. Both can be turned off in the notification settings. A private repository's are worked out from this server's index of its space with the choices the main index keeps.

What the pages and views say. getRepo's viewer.subscription says how the viewer watches it. getThread's viewer.subscription says what it chose, and viewer.notifiedFor why it hears of the thread without a choice: as its author, as one who commented, or watching the repository.

On the pages. A Watch menu beside Fork and Star, for an account logged in: Participating, All activity, Releases, Ignore. A Subscribe button in a pull's or an issue's head, its title saying why the account hears of it. Unsubscribing from one it hears of for its part in it mutes it. Notifications word what a watched repository did, a release among them, and the settings list the two reasons.

Command line and MCP. knotless notifications watch, subscribe, mute, unsubscribe and subscriptions, and the MCP subscribe tool. The two methods join the login's scope, so a login made before this logs in again.

Why

This is the Subscribe and mute item on Basic forge features missing, from archive downloads to webhooks. Notifications followed fixed rules: there was no way to follow a thread or repository one had no part in, nor to quiet one.

The levels follow what GitHub, GitLab and Gitea share: participating by default, a level per repository, and a switch per thread over it. Choices are private, as Bluesky keeps thread mutes. A new index on forge by repository and createdAt keeps a watched repository's records a range seek.

How it was checked

• A unit test in index.rs: watching at each level, what is heard once and for which reason, subscribing from a time, muting a thread one wrote, a review asked through a mute, choices given from another index, and the limit.
• An MCP test of the tool and the commands, over an appview.
• A gateway test of the methods from the pages: each level, the views' viewer states, paging, and each refusal.
• An e2e flow: watching a repository and back, and unsubscribing from an issue its author wrote, then subscribing again, each read back on the page.
• The query plans gate, on CI. The shots check moved no page, as the controls show only to an account logged in.

Shortcomings

There is no mute on a notification's row, as an action on every row of the list would crowd it: muting is done from the thread.

Changing a repository's level starts it counting again from then.

This adds watch levels for a repository and subscribe/mute for a pull or issue. It adds the putSubscription and listSubscriptions methods, the subscribed and watching notification reasons, the viewer fields, and the CLI and MCP surface. A changeset is included. The handler code I read (web/subscriptions.rs) looks sound: levels are validated per subject kind, the per-account limit is enforced, and repositories are keyed by owner and key.

I could not read the full 90 KB diff in this session. I looked at the handler, the lexicon search hits and the file listings, not at index.rs or its tests. Only web has passed so far. check, test, lexicons, shots, docs and e2e were still running or queued when I looked, so I have no result for them.

Docs are missing. AGENTS.md requires a change to update the docs in the same pull. A search of docs/ at the head for subscription finds only the unrelated reviewer guide, so none of these pages mention the change:

• docs/reference/api.md needs the two new methods, the two new reasons in listNotifications, and the new viewer.subscription and viewer.notifiedFor fields.
• docs/reference/cli.md needs notifications watch, subscribe, mute, unsubscribe and subscriptions.
• docs/reference/mcp.md needs the subscribe tool.
• docs/design/serve.md needs how the appview keeps the choices, and the new index on forge.
• docs/design/access.md should say how a private repository's notifications are worked out from the space index.

Body wording. The "Shortcomings" section says the page controls are "still to come in this pull". If they are not in this pull, reword it to say they come in a later one, so the description matches what lands.

The docs I asked for are now in the pull. docs/reference/api.md has putSubscription, listSubscriptions and the new subscribed and watching reasons. docs/reference/cli.md has the new notifications commands. docs/reference/mcp.md has the subscribe tool and the two reasons in notification_settings. docs/design/serve.md covers the stored choices, and docs/design/access.md lists the new methods among the rpc: scope.

I did not confirm that the index.rs private-repo wording is in access.md, and I did not read index.rs or its tests. Every CI check on this commit was still queued when I looked, so none has a result yet. Please make sure check, test, lexicons, docs and the query-plans gate pass before you merge.

The body's "Shortcomings" section still says the page controls are "still to come in this pull". If they are not in this pull, reword it to say a later pull adds them.

This pull adds watch levels for a repository, subscribe and mute for a pull or issue, the subscribed and watching notification reasons, and the CLI and MCP surface. The docs I asked for in round 1 are in. The latest commit only adds test coverage for paging subscriptions. I found nothing new that must change.

I did not read index.rs or its tests line by line. Every check on this commit (check, test, lexicons, docs, web, shots, e2e) was still queued when I looked. Please make sure they all pass, including the query-plans gate, before you merge.

The body's "Shortcomings" section is now stale. The second commit added the Watch menu and Subscribe button on the pages, but the section still says the controls are "still to come in this pull". Reword or remove it so the description matches what lands.

The only change since my last review is a merge of main, which had one conflict in index.rs. I found nothing that must change. The "Shortcomings" section of the body now matches what lands, so that earlier request is done. The docs from round 1 are still in.

Checks on this commit: check, lexicons and docs passed. test, shots and e2e were still running, and web was still queued. The pull is also in the merge queue, which will run the checks again on the batch. I did not re-read the conflict resolution in index.rs line by line, so rely on test and the query-plans gate for that. Merge only once they pass.