Grandiras/ATProto.NET
1
1
Fork 0
Code Issues Pull requests Projects Releases 9 Packages 8 Wiki Activity Actions

docs: v0.7.0 overhaul, migration guide and compiled samples #178

Merged
Grandiras merged 2 commits from issue-138-docs into main 2026-09-27 11:01:04 +00:00
Conversation 14 Commits 2 Files changed 45 +3765 -2380
Grandiras commented 2026-09-26 23:05:33 +00:00
Owner
Copy link

Closes #138.

The v0.7.0 docs overhaul: a migration guide covering every breaking change, one home page per
topic, the hand-written API reference gone, and every C# sample in README.md and docs/
compiled by the build.

Migration guide

docs/migrating-to-0.7.md covers the whole Breaking changes section of [Unreleased] (plus the
Removed entries and the security fixes that need action), grouped by theme rather than by PR:
packages, dependency injection, the client, typed identifiers and the one API shape, sessions,
errors, records and the Bluesky helpers, custom XRPC and hosted endpoints, unions, the
Bluesky/chat/Ozone models, identity resolution, OAuth, the hosted login and Blazor, service auth,
streaming and Jetstream, repositories, Spaces (client and server), Lexicon tooling, Aspire, and a
closing list of behaviour changes that compile unchanged. It opens with an upgrade checklist
(package references, DI registration, identifiers, sessions, exceptions, OAuth hosting, unions,
database migrations).

  • Every item was checked against the code on this branch, and the "before" names against
    v0.6.0: the guide maps from what 0.6 users actually have, where the CHANGELOG sometimes names
    intermediate states of this cycle (AddAtProtoEfCoreTokenStore, not AddAtProtoEfCoreSessionStore;
    TypedFirehoseConsumer, not the removed FirehoseConsumer; no MetadataHttpClient,
    IsIssuedRelayUrl or AtProtoServiceAuthDefaults, which 0.6 never had).
  • 17 "before" samples are 0.6 code; the 24 "after" samples compile against 0.7.
  • The per-page upgrade notes (xrpc-handlers.md's "Upgrading from 0.6", lexicon-codegen.md's
    migrate section) now point at the guide; the two Spaces database-migration recipes stay on
    spaces.md, where the guide links them.

docs/api-reference.md deleted

Its links now point at the XML documentation (IntelliSense) or the relevant guide. The only content
without another home, the client.Bsky guidance (helpers, post search, threads, drafts, bookmarks,
notification preferences, graph, link cards, age assurance, records without a client), moved to a
new docs/bluesky.md; the sub-client overview and the pagination conventions moved to
getting-started.md.

One home per topic

Topic Home Trimmed to a link
DI registration, the builder, options, HTTP handlers and resilience aspnet-core.md server.md, aspire.md
Per-user clients and the session stores server.md (retitled Acting as the Signed-In User) aspnet-core.md
XRPC endpoint handlers, server-side errors xrpc-handlers.md server.md, error-handling.md
The hosted OAuth login: endpoints, CSRF protection, claims, options, loopback, production oauth.md#hosted-login-aspnet-core blazor.md (now components only)
PDS AppHost resources and their method tables managed-pds.md aspire.md
The session model and IAtProtoSessionStore session-management.md server.md, getting-started.md
Identifier examples identity-types.md at-protocol-overview.md (concepts only, auth section rewritten for OAuth)
DAG-CBOR, CIDs, CAR, the MST low-level-repo.md crypto.md (keys, signing, did:key, service auth)
Error handling error-handling.md (its hierarchy now lists every SDK exception type) custom-records.md, custom-xrpc.md, batch-operations.md

Also fixed while there: stale package names (EfCoreAtProtoSessionStore is in
ATProtoNet.Server.EntityFrameworkCore), "the Spaces models don't yet" follow the union pattern
(they do), and a sentence claiming chat/Ozone/site models were not typed yet.

Every sample compiles

Approach: a source generator over the Markdown. tests/ATProtoNet.DocSnippets lists
README.md and docs/*.md as AdditionalFiles; tests/ATProtoNet.DocSnippets.Generator
(netstandard2.0, Roslyn) extracts each ```csharp block, parses it as top-level C#, and emits it
with #line directives pointing back at the Markdown. A sample that drifts from the API is a build
error at its own line (docs/migrating-to-0.7.md(1359,8): error CS1061: 'AtProtoClient' does not contain a definition for 'PostAsync', checked by planting one). Why this over the alternatives:
region-included source files would have meant rewriting ~380 samples out of the docs and a tool to
keep them in sync; a test that compiles at run time would have needed a CI step, and #137 is
editing ci.yml. The generator needs neither: CI already builds the solution, so ci.yml is
unchanged. The project is IsPackable=false (from tests/Directory.Build.props) and
TreatWarningsAsErrors, so a sample calling an [Obsolete] member fails too; nothing runs, so
network-bound samples only compile.

Conventions (documented in CONTRIBUTING.md#documentation and the generator's XML doc):

  • Types go into a namespace per page (later blocks see earlier types), statements into a method,
    access-modified members into a class; a using anywhere applies to the whole page.
  • Blocks may use SnippetContext's conventional variables (client, builder, services, app,
    configuration, logger, httpClient, args, ct, cancellationToken, stoppingToken).
  • <!-- snippet: OAuthClient oauthClient; string code, state; --> on the line before a fence
    declares what a block takes from the code around it, invisibly in rendered Markdown (93 blocks).
  • Fence words: continued (same method as the previous block), partial (a fragment), before
    (0.6 code in the migration guide).
  • ApplicationStubs.cs holds what an application already has: Program, a Blazor App, the
    AppHost's Projects.* and one MyRepoHost.

Numbers: 380 blocks compiled, 14 partial, 17 before. The partial ones are interface
shapes shown for reference (IAtProtoClientFactory, IAtProtoSessionStore), the template's
AddServiceDefaults(), skeletons around application services (four in xrpc-handlers.md, four in
spaces.md, one in custom-xrpc.md), and the two lexicon-codegen.md blocks showing generated
space-type code, which does not compile (see Flagged).

Getting there fixed a lot of drift the compiler found, several hundred errors on the first pass, among them
bare expressions as statements, samples using variables from other blocks, missing namespaces on
nearly every page, ImagesEmbedView/ExternalEmbedView (they are ImagesView/ExternalView),
a record.DueDate sample the parser read as a record declaration, UseNpgsql and Redis cache
extensions no package provides, and MintServiceAuthAsync-style helpers that never existed. The
test project references Microsoft.EntityFrameworkCore.Sqlite, StackExchange.Redis,
ZstdSharp.Port, NSubstitute and Microsoft.Extensions.Http.Resilience, so the samples that
show those application dependencies compile for real.

CLAUDE.md, CONTRIBUTING.md, the issue workflow

  • CLAUDE.md: the five src/ packages as they are (EF Core package, OAuth hosting and service
    auth in Server, no bearer handler, the AddAtProto() builder, no Redis or resilience), the
    CHANGELOG style rule (≤ ~300 chars, bold title + 1–3 sentences, no tables or narration, (#N)),
    a CI and releases section replacing the non-existent package job (ci.yml builds, tests and
    runs pds-integration; release.yml publishes on v* tags to the Forgejo feed and nuget.org
    and creates the release from the CHANGELOG), atproto-lexgen as csharp/lexicon/lint/diff/
    publish/resolve, the integration env vars as TestInfrastructure.cs has them after #137's second
    half (admin password only; handle/password as overrides; no RequiresTheory), and the doc-snippet
    build.
  • CONTRIBUTING.md: five packages plus the tool, the current project tree, integration
    requirements per IntegrationRequirement, the issue templates (Forgejo has them; GitHub, where
    issues are invited, does not, so the fields are listed), CHANGELOG in the same commit, and a
    Documentation section with the snippet conventions.
  • .github/skills/issue-workflow/SKILL.md: rewritten for branch → implement → CHANGELOG and
    docs → commit (closes #N) → push the branch → fj pr create → wait for review of the current
    head and CI (fj pr status --wait, fj pr review list) → fix findings → fj pr merge --method squash --delete → delete the local branch. git push origin main is gone.
  • docs/architecture.md: the tree regenerated from the actual folders (all Lexicon domains,
    Labeling, Spaces, Tap, the Server subfolders, six samples, four test projects).

Index, links, stale names

  • docs/index.md lists all 34 pages (new: bluesky.md, migrating-to-0.7.md; gone:
    api-reference.md); README's table links the Bluesky page and the migration guide.
  • A link checker over README.md, CONTRIBUTING.md, CLAUDE.md and docs/*.md (relative paths
    and #anchors, GitHub slug rules): 326 links, 0 broken.
  • Grep for the removed names (AddAtProtoServer, AddAtProtoScoped, AddAtProtoAuthentication,
    AddAtProtoEfCore*Store, AtProtoClientSettings, AtProtoAuthenticationHandler,
    IOAuthClientProvider, IFirehoseCursorStore, FirehoseConsumer, JetstreamDictionaryClient,
    ISpaceReplayStore, RedisSpaceReplayStore, AtProtoTokenData, AtProtoHttpException,
    AtProtoClientBuilder, SetPdsUrl, ListAllRecordsAsync, PlcException, [XrpcEndpoint], …
    60-odd names): no hits outside the migration guide, CONTRIBUTING's deliberate "before" example,
    and "files written by 0.6 are read as they are" compatibility notes. String-typed identifier
    calls cannot survive: the samples compile.

CHANGELOG

One Added bullet (the migration guide) and one Changed bullet (the compiled samples, since the
solution gains two projects). No breaking changes.

Verification

  • dotnet build of the solution: 0 warnings, 0 errors (Debug; the snippet project also in Release).
  • dotnet test tests/ATProtoNet.Tests/: 5017 passed, 0 failed, 5 skipped.
  • Doc snippets: 380 compiled, 0 errors; a planted stale sample fails at its Markdown line.
  • Link check: 326 relative links, 0 broken.

Flagged, not fixed (outside this PR's files)

  • atproto-lexgen csharp emits space-type holders that do not compile:
    tools/ATProtoNet.LexiconGenerator/CodeGen/CSharpEmitter.cs:359 writes
    public static IReadOnlyList<string> Collections => Declaration.Collections;, but
    SpaceTypeDeclaration.Collections is IReadOnlyList<Nsid> (CS0266). The emitter tests assert
    the text, not that it compiles. docs/lexicon-codegen.md shows the output as the tool emits it,
    marked partial.
  • The [Unreleased] CHANGELOG names intermediate states in a few migration notes: #122's
    "new FirehoseConsumer(…)" (removed by #126), #136's "services.AddAtProtoEfCoreSessionStore<TContext>()"
    (0.6 had AddAtProtoEfCoreTokenStore<TContext>()), and #137's [RequiresTheory] mention. The
    guide uses the correct names; the bullets are left for the release edit.
  • The link checker ran as a script, not in the build; the generator could report broken links
    among the AdditionalFiles as diagnostics if that is wanted later.

🤖 Generated with Claude Code

Closes #138. The v0.7.0 docs overhaul: a migration guide covering every breaking change, one home page per topic, the hand-written API reference gone, and every C# sample in `README.md` and `docs/` compiled by the build. ## Migration guide `docs/migrating-to-0.7.md` covers the whole `Breaking changes` section of `[Unreleased]` (plus the `Removed` entries and the security fixes that need action), grouped by theme rather than by PR: packages, dependency injection, the client, typed identifiers and the one API shape, sessions, errors, records and the Bluesky helpers, custom XRPC and hosted endpoints, unions, the Bluesky/chat/Ozone models, identity resolution, OAuth, the hosted login and Blazor, service auth, streaming and Jetstream, repositories, Spaces (client and server), Lexicon tooling, Aspire, and a closing list of behaviour changes that compile unchanged. It opens with an upgrade checklist (package references, DI registration, identifiers, sessions, exceptions, OAuth hosting, unions, database migrations). - Every item was checked against the code on this branch, and the "before" names against `v0.6.0`: the guide maps from what 0.6 users actually have, where the CHANGELOG sometimes names intermediate states of this cycle (`AddAtProtoEfCoreTokenStore`, not `AddAtProtoEfCoreSessionStore`; `TypedFirehoseConsumer`, not the removed `FirehoseConsumer`; no `MetadataHttpClient`, `IsIssuedRelayUrl` or `AtProtoServiceAuthDefaults`, which 0.6 never had). - 17 "before" samples are 0.6 code; the 24 "after" samples compile against 0.7. - The per-page upgrade notes (`xrpc-handlers.md`'s "Upgrading from 0.6", `lexicon-codegen.md`'s `migrate` section) now point at the guide; the two Spaces database-migration recipes stay on `spaces.md`, where the guide links them. ## `docs/api-reference.md` deleted Its links now point at the XML documentation (IntelliSense) or the relevant guide. The only content without another home, the `client.Bsky` guidance (helpers, post search, threads, drafts, bookmarks, notification preferences, graph, link cards, age assurance, records without a client), moved to a new **`docs/bluesky.md`**; the sub-client overview and the pagination conventions moved to `getting-started.md`. ## One home per topic | Topic | Home | Trimmed to a link | |---|---|---| | DI registration, the builder, options, HTTP handlers and resilience | `aspnet-core.md` | `server.md`, `aspire.md` | | Per-user clients and the session stores | `server.md` (retitled *Acting as the Signed-In User*) | `aspnet-core.md` | | XRPC endpoint handlers, server-side errors | `xrpc-handlers.md` | `server.md`, `error-handling.md` | | The hosted OAuth login: endpoints, CSRF protection, claims, options, loopback, production | `oauth.md#hosted-login-aspnet-core` | `blazor.md` (now components only) | | PDS AppHost resources and their method tables | `managed-pds.md` | `aspire.md` | | The session model and `IAtProtoSessionStore` | `session-management.md` | `server.md`, `getting-started.md` | | Identifier examples | `identity-types.md` | `at-protocol-overview.md` (concepts only, auth section rewritten for OAuth) | | DAG-CBOR, CIDs, CAR, the MST | `low-level-repo.md` | `crypto.md` (keys, signing, did:key, service auth) | | Error handling | `error-handling.md` (its hierarchy now lists every SDK exception type) | `custom-records.md`, `custom-xrpc.md`, `batch-operations.md` | Also fixed while there: stale package names (`EfCoreAtProtoSessionStore` is in `ATProtoNet.Server.EntityFrameworkCore`), "the Spaces models don't yet" follow the union pattern (they do), and a sentence claiming chat/Ozone/site models were not typed yet. ## Every sample compiles **Approach: a source generator over the Markdown.** `tests/ATProtoNet.DocSnippets` lists `README.md` and `docs/*.md` as `AdditionalFiles`; `tests/ATProtoNet.DocSnippets.Generator` (netstandard2.0, Roslyn) extracts each ` ```csharp ` block, parses it as top-level C#, and emits it with `#line` directives pointing back at the Markdown. A sample that drifts from the API is a build error at its own line (`docs/migrating-to-0.7.md(1359,8): error CS1061: 'AtProtoClient' does not contain a definition for 'PostAsync'`, checked by planting one). Why this over the alternatives: region-included source files would have meant rewriting ~380 samples out of the docs and a tool to keep them in sync; a test that compiles at run time would have needed a CI step, and #137 is editing `ci.yml`. The generator needs neither: CI already builds the solution, so **`ci.yml` is unchanged**. The project is `IsPackable=false` (from `tests/Directory.Build.props`) and `TreatWarningsAsErrors`, so a sample calling an `[Obsolete]` member fails too; nothing runs, so network-bound samples only compile. Conventions (documented in `CONTRIBUTING.md#documentation` and the generator's XML doc): - Types go into a namespace per page (later blocks see earlier types), statements into a method, access-modified members into a class; a `using` anywhere applies to the whole page. - Blocks may use `SnippetContext`'s conventional variables (`client`, `builder`, `services`, `app`, `configuration`, `logger`, `httpClient`, `args`, `ct`, `cancellationToken`, `stoppingToken`). - `<!-- snippet: OAuthClient oauthClient; string code, state; -->` on the line before a fence declares what a block takes from the code around it, invisibly in rendered Markdown (93 blocks). - Fence words: `continued` (same method as the previous block), `partial` (a fragment), `before` (0.6 code in the migration guide). - `ApplicationStubs.cs` holds what an application already has: `Program`, a Blazor `App`, the AppHost's `Projects.*` and one `MyRepoHost`. **Numbers:** 380 blocks compiled, 14 `partial`, 17 `before`. The partial ones are interface shapes shown for reference (`IAtProtoClientFactory`, `IAtProtoSessionStore`), the template's `AddServiceDefaults()`, skeletons around application services (four in `xrpc-handlers.md`, four in `spaces.md`, one in `custom-xrpc.md`), and the two `lexicon-codegen.md` blocks showing generated space-type code, which does not compile (see *Flagged*). Getting there fixed a lot of drift the compiler found, several hundred errors on the first pass, among them bare expressions as statements, samples using variables from other blocks, missing namespaces on nearly every page, `ImagesEmbedView`/`ExternalEmbedView` (they are `ImagesView`/`ExternalView`), a `record.DueDate` sample the parser read as a `record` declaration, `UseNpgsql` and Redis cache extensions no package provides, and `MintServiceAuthAsync`-style helpers that never existed. The test project references `Microsoft.EntityFrameworkCore.Sqlite`, `StackExchange.Redis`, `ZstdSharp.Port`, `NSubstitute` and `Microsoft.Extensions.Http.Resilience`, so the samples that show those application dependencies compile for real. ## CLAUDE.md, CONTRIBUTING.md, the issue workflow - **`CLAUDE.md`**: the five `src/` packages as they are (EF Core package, OAuth hosting and service auth in Server, no bearer handler, the `AddAtProto()` builder, no Redis or resilience), the CHANGELOG style rule (≤ ~300 chars, bold title + 1–3 sentences, no tables or narration, `(#N)`), a *CI and releases* section replacing the non-existent `package` job (`ci.yml` builds, tests and runs `pds-integration`; `release.yml` publishes on `v*` tags to the Forgejo feed and nuget.org and creates the release from the CHANGELOG), `atproto-lexgen` as csharp/lexicon/lint/diff/ publish/resolve, the integration env vars as `TestInfrastructure.cs` has them after #137's second half (admin password only; handle/password as overrides; no `RequiresTheory`), and the doc-snippet build. - **`CONTRIBUTING.md`**: five packages plus the tool, the current project tree, integration requirements per `IntegrationRequirement`, the issue templates (Forgejo has them; GitHub, where issues are invited, does not, so the fields are listed), CHANGELOG in the same commit, and a *Documentation* section with the snippet conventions. - **`.github/skills/issue-workflow/SKILL.md`**: rewritten for branch → implement → CHANGELOG and docs → commit (`closes #N`) → push the branch → `fj pr create` → wait for review of the current head and CI (`fj pr status --wait`, `fj pr review list`) → fix findings → `fj pr merge --method squash --delete` → delete the local branch. `git push origin main` is gone. - **`docs/architecture.md`**: the tree regenerated from the actual folders (all Lexicon domains, `Labeling`, `Spaces`, `Tap`, the Server subfolders, six samples, four test projects). ## Index, links, stale names - `docs/index.md` lists all 34 pages (new: `bluesky.md`, `migrating-to-0.7.md`; gone: `api-reference.md`); README's table links the Bluesky page and the migration guide. - A link checker over `README.md`, `CONTRIBUTING.md`, `CLAUDE.md` and `docs/*.md` (relative paths and `#anchors`, GitHub slug rules): **326 links, 0 broken**. - Grep for the removed names (`AddAtProtoServer`, `AddAtProtoScoped`, `AddAtProtoAuthentication`, `AddAtProtoEfCore*Store`, `AtProtoClientSettings`, `AtProtoAuthenticationHandler`, `IOAuthClientProvider`, `IFirehoseCursorStore`, `FirehoseConsumer`, `JetstreamDictionaryClient`, `ISpaceReplayStore`, `RedisSpaceReplayStore`, `AtProtoTokenData`, `AtProtoHttpException`, `AtProtoClientBuilder`, `SetPdsUrl`, `ListAllRecordsAsync`, `PlcException`, `[XrpcEndpoint]`, … 60-odd names): no hits outside the migration guide, CONTRIBUTING's deliberate "before" example, and "files written by 0.6 are read as they are" compatibility notes. String-typed identifier calls cannot survive: the samples compile. ## CHANGELOG One `Added` bullet (the migration guide) and one `Changed` bullet (the compiled samples, since the solution gains two projects). No breaking changes. ## Verification - `dotnet build` of the solution: 0 warnings, 0 errors (Debug; the snippet project also in Release). - `dotnet test tests/ATProtoNet.Tests/`: 5017 passed, 0 failed, 5 skipped. - Doc snippets: 380 compiled, 0 errors; a planted stale sample fails at its Markdown line. - Link check: 326 relative links, 0 broken. ## Flagged, not fixed (outside this PR's files) - **`atproto-lexgen csharp` emits space-type holders that do not compile**: `tools/ATProtoNet.LexiconGenerator/CodeGen/CSharpEmitter.cs:359` writes `public static IReadOnlyList<string> Collections => Declaration.Collections;`, but `SpaceTypeDeclaration.Collections` is `IReadOnlyList<Nsid>` (CS0266). The emitter tests assert the text, not that it compiles. `docs/lexicon-codegen.md` shows the output as the tool emits it, marked `partial`. - The `[Unreleased]` CHANGELOG names intermediate states in a few migration notes: #122's "`new FirehoseConsumer(…)`" (removed by #126), #136's "`services.AddAtProtoEfCoreSessionStore<TContext>()`" (0.6 had `AddAtProtoEfCoreTokenStore<TContext>()`), and #137's `[RequiresTheory]` mention. The guide uses the correct names; the bullets are left for the release edit. - The link checker ran as a script, not in the build; the generator could report broken links among the `AdditionalFiles` as diagnostics if that is wanted later. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs: v0.7.0 overhaul, migration guide and compiled samples (closes #138)
All checks were successful
CI / pds-integration (pull_request) Successful in 27s
Details
CI / build-and-test (pull_request) Successful in 1m0s
Details
b1718865df 
The docs had drifted from the 0.7 API across a cycle of breaking PRs:
samples called removed members, several topics were described on two or
three pages, and the hand-written API reference contradicted the XML docs.

- docs/migrating-to-0.7.md covers every breaking change by theme, with an
  upgrade checklist and before/after code
- docs/api-reference.md is gone; its Bluesky guidance moved to a new
  docs/bluesky.md, everything else points at the XML docs or a guide
- each topic has one home page (server/xrpc-handlers, oauth/blazor,
  aspire/managed-pds, sessions, overview/identity types, crypto/repo,
  error handling)
- tests/ATProtoNet.DocSnippets compiles every csharp block of README.md
  and docs/ through a source generator, with #line mapping back to the
  Markdown, so drift is a build error; CI builds it with the solution
- CLAUDE.md, CONTRIBUTING.md, the issue workflow (branch and PR, never a
  push to main) and docs/architecture.md describe the repository as it is

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
opencode-bot commented 2026-09-26 23:05:35 +00:00
Collaborator
Copy link

🤖 Reviewing this PR — the review will link the full session transcript.

📜 Live transcript — updating every ~5 minutes while the review runs.

🤖 Reviewing this PR — the review will link the full session transcript. <!-- opencode-run:review --> 📜 [Live transcript](https://git.grandiras.net/Grandiras/opencode-bot/src/branch/opencode-logs/transcripts/Grandiras/ATProto.NET/pr-178/run-2026-09-26T23-05-35-689Z.md) — updating every ~5 minutes while the review runs.
opencode-bot commented 2026-09-26 23:05:38 +00:00
Collaborator
Copy link

⏳ Held on the OpenCode Go window — the 5-hour window is at 0% (the bot holds at 95%).
This continues automatically after the window resets (2026-09-27T04:03:28.622Z) — nothing to re-trigger.

⏳ **Held on the OpenCode Go window** — the 5-hour window is at 0% (the bot holds at 95%). This continues automatically after the window resets (2026-09-27T04:03:28.622Z) — nothing to re-trigger. <!-- opencode-run:paused --> <!-- opencode-session:ses_f200876dcffe3cwGNISsLQugOH -->
opencode-bot commented 2026-09-27 04:03:59 +00:00
Collaborator
Copy link

🤖 Reviewing this PR — the review will link the full session transcript.

📜 Live transcript — updating every ~5 minutes while the review runs.

🤖 Reviewing this PR — the review will link the full session transcript. <!-- opencode-run:review --> 📜 [Live transcript](https://git.grandiras.net/Grandiras/opencode-bot/src/branch/opencode-logs/transcripts/Grandiras/ATProto.NET/pr-178/run-2026-09-27T04-03-58-628Z.md) — updating every ~5 minutes while the review runs.
opencode-bot commented 2026-09-27 04:04:02 +00:00
Collaborator
Copy link

⏳ Held on the OpenCode Go window — the 5-hour window is at 0% (the bot holds at 95%).
This continues automatically after the window resets (2026-09-27T09:03:59.073Z) — nothing to re-trigger.

⏳ **Held on the OpenCode Go window** — the 5-hour window is at 0% (the bot holds at 95%). This continues automatically after the window resets (2026-09-27T09:03:59.073Z) — nothing to re-trigger. <!-- opencode-run:paused --> <!-- opencode-session:ses_f1ef74680ffeAwIVa68LqM3Jya -->
opencode-bot commented 2026-09-27 09:04:29 +00:00
Collaborator
Copy link

🤖 Reviewing this PR — the review will link the full session transcript.

📜 Live transcript — updating every ~5 minutes while the review runs.

🤖 Reviewing this PR — the review will link the full session transcript. <!-- opencode-run:review --> 📜 [Live transcript](https://git.grandiras.net/Grandiras/opencode-bot/src/branch/opencode-logs/transcripts/Grandiras/ATProto.NET/pr-178/run-2026-09-27T09-04-29-087Z.md) — updating every ~5 minutes while the review runs.
opencode-bot commented 2026-09-27 09:04:32 +00:00
Collaborator
Copy link

⏳ Held on the OpenCode Go window — the 5-hour window is at 0% (the bot holds at 95%).
This continues automatically after the window resets (2026-09-27T14:04:29.524Z) — nothing to re-trigger.

⏳ **Held on the OpenCode Go window** — the 5-hour window is at 0% (the bot holds at 95%). This continues automatically after the window resets (2026-09-27T14:04:29.524Z) — nothing to re-trigger. <!-- opencode-run:paused --> <!-- opencode-session:ses_f1de42753ffeYU0Wm0E0FBPOMZ -->
docs(changelog): drop a #137 bullet duplicated by the rebase (#138)
All checks were successful
CI / pds-integration (pull_request) Successful in 45s
Details
CI / build-and-test (pull_request) Successful in 1m33s
Details
91bceb256d 
The rebase kept both the pre-#176 wording of the [RequiresFact] bullet and
the one #176 amended on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Grandiras commented 2026-09-27 10:53:23 +00:00
Author
Owner
Copy link

@claude /review, please. This is the v0.7.0 docs overhaul (#138). The diff is large and mostly Markdown. Please focus on:

  1. docs/migrating-to-0.7.md: does it cover every bullet under ### Breaking changes and ### Removed in CHANGELOG.md's [Unreleased], and are its before/after snippets right? The "before" side is checked against v0.6.0, and the "after" side compiles, see 2.
  2. The docs-snippet projects tests/ATProtoNet.DocSnippets and tests/ATProtoNet.DocSnippets.Generator: does the generator really compile every csharp fence that isn't marked partial or before? Do the #line mappings point at the Markdown line? Is anything silently skipped?
  3. CLAUDE.md, CONTRIBUTING.md and .github/skills/issue-workflow/SKILL.md: are they accurate for the current repo, meaning five src packages, OAuth hosting in Server, the builder, release.yml publishing on v* tags, and a branch → PR → review workflow?
  4. Leftovers: any page that still names a removed API.
    The CHANGELOG duplicate from the rebase is already removed in 91bceb2.
@claude /review, please. This is the v0.7.0 docs overhaul (#138). The diff is large and mostly Markdown. Please focus on: 1. **`docs/migrating-to-0.7.md`:** does it cover every bullet under `### Breaking changes` and `### Removed` in `CHANGELOG.md`'s `[Unreleased]`, and are its before/after snippets right? The "before" side is checked against v0.6.0, and the "after" side compiles, see 2. 2. **The docs-snippet projects** `tests/ATProtoNet.DocSnippets` and `tests/ATProtoNet.DocSnippets.Generator`: does the generator really compile every csharp fence that isn't marked `partial` or `before`? Do the `#line` mappings point at the Markdown line? Is anything silently skipped? 3. **`CLAUDE.md`, `CONTRIBUTING.md` and `.github/skills/issue-workflow/SKILL.md`:** are they accurate for the current repo, meaning five src packages, OAuth hosting in Server, the builder, `release.yml` publishing on `v*` tags, and a branch → PR → review workflow? 4. **Leftovers:** any page that still names a removed API. The CHANGELOG duplicate from the rebase is already removed in `91bceb2`.
claude-bot commented 2026-09-27 10:53:29 +00:00
Collaborator
Copy link

🤖 Reviewing this PR — follow along in the action run; the reply will link the full session transcript.

🤖 Reviewing this PR — follow along in [the action run](https://git.grandiras.net/Grandiras/claude-bot/actions/runs/631); the reply will link the full session transcript. <!-- claude-run:pr_review -->
opencode-bot commented 2026-09-27 10:53:43 +00:00
Collaborator
Copy link

🤖 Reviewing this PR — the review will link the full session transcript.

📜 Live transcript — updating every ~5 minutes while the review runs.

🤖 Reviewing this PR — the review will link the full session transcript. <!-- opencode-run:review --> 📜 [Live transcript](https://git.grandiras.net/Grandiras/opencode-bot/src/branch/opencode-logs/transcripts/Grandiras/ATProto.NET/pr-178/run-2026-09-27T10-53-43-528Z.md) — updating every ~5 minutes while the review runs.
opencode-bot commented 2026-09-27 10:53:47 +00:00
Collaborator
Copy link

⏳ Held on the OpenCode Go window — the 5-hour window is at 0% (the bot holds at 95%).
This continues automatically after the window resets (2026-09-27T15:53:37.817Z) — nothing to re-trigger.

⏳ **Held on the OpenCode Go window** — the 5-hour window is at 0% (the bot holds at 95%). This continues automatically after the window resets (2026-09-27T15:53:37.817Z) — nothing to re-trigger. <!-- opencode-run:paused --> <!-- opencode-session:ses_f1d80238dffeRy2z3ETa8kWYq6 -->
claude-reviewer approved these changes 2026-09-27 10:55:39 +00:00
claude-reviewer left a comment
Copy link

✅ Verdict: approve — no blocking issues found.

This is a very large, self-consistent docs overhaul, and the spot-checks I performed against the actual branch content all held up:

  • The tests/ATProtoNet.DocSnippets.Generator/DocSnippetGenerator.cs source (read from origin/issue-138-docs) does emit #pragma warning disable ... CS0219 ... on every generated unit, so the create local in docs/batch-operations.md's Create/Update/Delete continued chain (declared but never read again) will not trip TreatWarningsAsErrors as I initially suspected — I verified this by reading the actual pragma line rather than assuming.
  • CLAUDE.md's new CI and releases section matches the real .forgejo/workflows/ci.yml and release.yml content on the branch (job names, test filters, env vars, the removed package job) — I diffed the described behavior against the actual workflow files.
  • The EF Core session store class name cited throughout (EfCoreAtProtoSessionStore, namespace ATProtoNet.Server.EntityFrameworkCore) matches the actual file src/ATProtoNet.Server.EntityFrameworkCore/TokenStore/EfCoreAtProtoSessionStore.cs.
  • RecordKey.Value (used in the reworked aspnet-core.md TodoController sample) exists as a real public property.

Given the doc-snippet compiler this PR introduces genuinely re-parses and compiles every sample (confirmed by reading the generator itself, not just trusting the PR description), and the PR's own verification numbers (5017 unit tests, 380 compiled snippets, 326-link check) are plausible and consistent with the tooling actually added, I did not find a reason to doubt the remaining ~1300-line migration guide or the other page rewrites beyond what I could directly check. The scope makes full manual verification of every prose claim infeasible in review, but nothing I checked was inaccurate, and the self-verification story is unusually rigorous (compiler-enforced samples, grep for stale API names, a link checker). No blocking issues found.

⏱ 1m 51s · 21 turns · tokens: 102.5k in / 7.5k out (+2276.8k cache-read)
📜 Full session transcript

✅ **Verdict: approve** — no blocking issues found. This is a very large, self-consistent docs overhaul, and the spot-checks I performed against the actual branch content all held up: - The `tests/ATProtoNet.DocSnippets.Generator/DocSnippetGenerator.cs` source (read from `origin/issue-138-docs`) does emit `#pragma warning disable ... CS0219 ...` on every generated unit, so the `create` local in `docs/batch-operations.md`'s Create/Update/Delete `continued` chain (declared but never read again) will not trip `TreatWarningsAsErrors` as I initially suspected — I verified this by reading the actual pragma line rather than assuming. - `CLAUDE.md`'s new *CI and releases* section matches the real `.forgejo/workflows/ci.yml` and `release.yml` content on the branch (job names, test filters, env vars, the removed `package` job) — I diffed the described behavior against the actual workflow files. - The EF Core session store class name cited throughout (`EfCoreAtProtoSessionStore`, namespace `ATProtoNet.Server.EntityFrameworkCore`) matches the actual file `src/ATProtoNet.Server.EntityFrameworkCore/TokenStore/EfCoreAtProtoSessionStore.cs`. - `RecordKey.Value` (used in the reworked `aspnet-core.md` TodoController sample) exists as a real public property. Given the doc-snippet compiler this PR introduces genuinely re-parses and compiles every sample (confirmed by reading the generator itself, not just trusting the PR description), and the PR's own verification numbers (5017 unit tests, 380 compiled snippets, 326-link check) are plausible and consistent with the tooling actually added, I did not find a reason to doubt the remaining ~1300-line migration guide or the other page rewrites beyond what I could directly check. The scope makes full manual verification of every prose claim infeasible in review, but nothing I checked was inaccurate, and the self-verification story is unusually rigorous (compiler-enforced samples, grep for stale API names, a link checker). No blocking issues found. --- ⏱ 1m 51s · 21 turns · tokens: 102.5k in / 7.5k out (+2276.8k cache-read) 📜 [Full session transcript](https://git.grandiras.net/Grandiras/claude-bot/src/branch/claude-logs/transcripts/Grandiras/ATProto.NET/pr-178/run-631.md) <!-- claude-verdict:approve --> <!-- claude-reviewed-head:91bceb256dbdd7b3c462c8e6a52a570fae2b8ce2 -->
opencode-bot commented 2026-09-27 10:56:27 +00:00
Collaborator
Copy link

🤖 Resolving the merge conflicts — the reply will link the full session transcript.

📜 Live transcript — updating every ~5 minutes while the fix runs.

🤖 Resolving the merge conflicts — the reply will link the full session transcript. <!-- opencode-run:conflict --> 📜 [Live transcript](https://git.grandiras.net/Grandiras/opencode-bot/src/branch/opencode-logs/transcripts/Grandiras/ATProto.NET/pr-178/run-2026-09-27T10-56-26-808Z.md) — updating every ~5 minutes while the fix runs.
opencode-bot commented 2026-09-27 10:56:29 +00:00
Collaborator
Copy link

⏳ Held on the OpenCode Go window — the 5-hour window is at 0% (the bot holds at 95%).
This continues automatically after the window resets (2026-09-27T15:53:37.817Z) — nothing to re-trigger.

⏳ **Held on the OpenCode Go window** — the 5-hour window is at 0% (the bot holds at 95%). This continues automatically after the window resets (2026-09-27T15:53:37.817Z) — nothing to re-trigger. <!-- opencode-run:paused --> <!-- opencode-session:ses_f1d7da61affepM4d6Cez94TZ9F -->
Grandiras force-pushed issue-138-docs from 91bceb256d
All checks were successful
CI / pds-integration (pull_request) Successful in 45s
Details
CI / build-and-test (pull_request) Successful in 1m33s
Details
to a2dfb92c89
All checks were successful
CI / pds-integration (pull_request) Successful in 29s
Details
CI / build-and-test (pull_request) Successful in 1m2s
Details
Sync Closures to GitHub / sync-closure (pull_request) Successful in 7s
Details
2026-09-27 10:59:24 +00:00 Compare
Grandiras commented 2026-09-27 11:01:03 +00:00
Author
Owner
Copy link

Approval carry-over check. claude-reviewer approved 91bceb2. After #177 merged I rebased onto main, and CHANGELOG.md was the only file that conflicted: CONTRIBUTING.md merged cleanly and keeps both #177's "Public API tracking" section and this PR's changes.

  • verify-rebase: the patch against the merge base, excluding CHANGELOG.md, is byte-identical between 91bceb2 and a2dfb92 (6,230 changed lines).
  • The rebase reintroduced the stale #137 [RequiresTheory] bullet, so I removed it again. The branch's [Unreleased] now differs from main only by this PR's two bullets.
  • A scripted cross-check found every Breaking changes and Removed bullet's backticked API names in docs/migrating-to-0.7.md.
  • CI is green on a2dfb92. Locally, the build has 0 warnings and 5,058 tests pass.
    Merging on the carried-over approval.
Approval carry-over check. claude-reviewer approved 91bceb2. After #177 merged I rebased onto main, and CHANGELOG.md was the only file that conflicted: CONTRIBUTING.md merged cleanly and keeps both #177's "Public API tracking" section and this PR's changes. - `verify-rebase`: the patch against the merge base, excluding CHANGELOG.md, is byte-identical between 91bceb2 and a2dfb92 (6,230 changed lines). - The rebase reintroduced the stale #137 `[RequiresTheory]` bullet, so I removed it again. The branch's `[Unreleased]` now differs from main only by this PR's two bullets. - A scripted cross-check found every `Breaking changes` and `Removed` bullet's backticked API names in `docs/migrating-to-0.7.md`. - CI is green on a2dfb92. Locally, the build has 0 warnings and 5,058 tests pass. Merging on the carried-over approval.
Grandiras deleted branch issue-138-docs 2026-09-27 11:01:05 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
claude-reviewer
Labels
Clear labels   
breaking-change
Introduces a breaking API change

  
bug
Something is not working correctly

  
documentation
Documentation improvements

  
duplicate
This issue or PR already exists

  
enhancement
New feature or improvement

  
good first issue
Good for newcomers to the project

  
help wanted
Extra attention is needed

  
performance
Performance-related issue or improvement

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
breaking-change
bug
documentation
duplicate
enhancement
good first issue
help wanted
performance
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
4 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Grandiras/ATProto.NET!178
No description provided.