docs: Sprint 5 caching ADR and XML doc stubs - #119
Conversation
…print5) - Add docs/adr/sprint5-caching-abstraction.md (ADR for IBlogPostCacheService) - Add docs/sprint5-xml-doc-stubs.md (XML doc stubs for Sam to apply) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
🏗️ PR Added to Squad Triage QueueThis PR has been labeled with Next steps:
|
github-actions
Bot
added
the
squad
|
Closing as redundant. Both |
There was a problem hiding this comment.
Pull request overview
Adds Sprint 5 documentation artifacts to support the upcoming caching abstraction work by recording the architectural decision and providing implementation-ready XML doc stubs.
Changes:
- Added an ADR documenting the decision to extract
IBlogPostCacheService/BlogPostCacheServiceand centralize cache keys. - Added a “ready-to-paste” XML doc stub pack for the new caching types and noted README sections needing follow-up updates.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/adr/sprint5-caching-abstraction.md | New ADR capturing context/decision/status/consequences for the caching abstraction. |
| docs/sprint5-xml-doc-stubs.md | New markdown document containing XML doc comment stubs and README update guidance for Sprint 5. |
| # Sprint 5 — XML Doc Comment Stubs | ||
|
|
There was a problem hiding this comment.
This markdown file doesn’t follow the repo’s markdown validator rules: it starts with an H1 and has no YAML front matter. Per .github/instructions/markdown.instructions.md, docs should include YAML front matter and avoid H1 headings (start content at H2+). Add the required front matter block and change the first heading to ## (or restructure so there’s no H1).
| # Sprint 5 — XML Doc Comment Stubs | |
| --- | |
| post_title: "Sprint 5 — XML Doc Comment Stubs" | |
| author1: "Frodo" | |
| post_slug: "sprint5-xml-doc-stubs" | |
| microsoft_alias: "unknown" | |
| featured_image: "" | |
| categories: [] | |
| tags: | |
| - xml-docs | |
| - caching | |
| - redis | |
| - sprint-5 | |
| ai_note: "No" | |
| summary: "XML documentation comment stubs for the Sprint 5 blog post caching abstraction and related README updates." | |
| post_date: "2026-04-23" | |
| --- | |
| ## Sprint 5 — XML Doc Comment Stubs |
| /// <summary> | ||
| /// Removes the all-posts cache entry from both L1 (in-memory) and L2 (Redis). | ||
| /// Call this after any write operation that affects the full post list | ||
| /// (create, edit, delete, publish/unpublish). | ||
| /// </summary> | ||
| /// <param name="ct">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param> | ||
| /// <returns>A <see cref="Task"/> that represents the asynchronous invalidation operation.</returns> | ||
| Task InvalidateAllAsync(CancellationToken ct); | ||
|
|
||
| /// <summary> | ||
| /// Removes the per-post cache entry for the given identifier from both | ||
| /// L1 (in-memory) and L2 (Redis). | ||
| /// Call this after any write operation that modifies or deletes a specific post. | ||
| /// </summary> | ||
| /// <param name="id">The unique identifier of the blog post whose cache entry should be removed.</param> | ||
| /// <param name="ct">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param> | ||
| /// <returns>A <see cref="Task"/> that represents the asynchronous invalidation operation.</returns> | ||
| Task InvalidateByIdAsync(Guid id, CancellationToken ct); | ||
| } |
There was a problem hiding this comment.
The PR description says the stubs cover RemoveAllAsync/RemoveByIdAsync, but the stubs here define InvalidateAllAsync/InvalidateByIdAsync. Please align the PR description and the doc stubs (method names + any references) so the intended API surface is unambiguous for the implementer.
|
|
||
| ### Registration | ||
|
|
||
| `BlogPostCacheService` is registered in `Program.cs` as a scoped or singleton service alongside `IMemoryCache` and the Redis `IDistributedCache`. |
There was a problem hiding this comment.
The ADR should capture a concrete decision, but this line says the service is registered as “scoped or singleton”. Please choose the intended lifetime (and ideally note why that lifetime is correct given the dependencies like IMemoryCache/IDistributedCache) so implementers don’t make inconsistent DI choices.
| `BlogPostCacheService` is registered in `Program.cs` as a scoped or singleton service alongside `IMemoryCache` and the Redis `IDistributedCache`. | |
| `BlogPostCacheService` is registered in `Program.cs` as a singleton service alongside `IMemoryCache` and the Redis `IDistributedCache`, because it is a stateless wrapper over shared cache dependencies and does not require per-request state. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## sprint/5-redis-caching #119 +/- ##
==========================================================
- Coverage 78.19% 70.38% -7.81%
==========================================================
Files 40 43 +3
Lines 642 672 +30
Branches 107 111 +4
==========================================================
- Hits 502 473 -29
- Misses 95 147 +52
- Partials 45 52 +7 🚀 New features to boost your workflow:
|
Summary
Working as Frodo (Tech Writer) · closes #114
Assessed documentation impact for the Sprint 5
IBlogPostCacheServiceextraction and produced two deliverables for the team.Changes
docs/adr/sprint5-caching-abstraction.mdArchitecture Decision Record documenting the decision to extract a dedicated
IBlogPostCacheServiceinterface from the four BlogPost CQRS handlers. Captures:JsonSerializerOptions, and hardcoded key strings across all handlersIBlogPostCacheService,BlogPostCacheService, andBlogPostCacheKeysdocs/sprint5-xml-doc-stubs.mdReady-to-paste XML doc comment stubs for Sam to apply when implementing:
IBlogPostCacheService– all 6 interface methods (GetAllAsync,SetAllAsync,GetByIdAsync,SetByIdAsync,RemoveAllAsync,RemoveByIdAsync)BlogPostCacheKeys– class and two constant membersBlogPostCacheService– class-level<remarks>blockNotes