Appearance
UC-028: Public Changelog Rendering Engine โ
๐ 1. Context & Problem Statement โ
Testers, product owners, and external users need a transparent, comprehensive view of implemented features, internal bug fixes, and database migrations without technical access to the Git repository or Markdown source files.
Solution: Expose a lightweight, cached rendering route at /changelog that reads the root /CHANGELOG.md file dynamically and parses it into a clean, modern UI layout.
โ๏ธ 2. Backend Logic & API (apps/api) โ
Endpoint: GET /api/changelog
- Read the physical file content from the project root
/CHANGELOG.mdusing the file system utility (fs.readFileSyncor standard runtime equivalent). - Error Handling: If the file is missing or unreadable, return a structured
HTTP 404or an empty fallback template instead of crashing the process. - Caching: Implement a basic in-memory caching mechanism or set cache-control headers (
stale-while-revalidate) so the server doesn't hit the disk on every single page refresh. - Return the raw text string inside a JSON payload:
{ content: string }.
๐จ 3. User Interface (apps/web) โ
Route: /changelog
- Fetch data from
GET /api/changelogon component mount or server render. - Use a standard markdown parsing utility (e.g.,
react-markdowncombined with typography styles like@tailwindcss/typography) to render the text. - Visual Structure: Ensure the distinct headers (
### Added,### Changed,### Fixed) are stylized with colored indicator chips or clean typography so testers can scan updates effortlessly.
๐งช 4. Testing Requirements โ
- Backend Tests: Validate that the endpoint accurately streams file data and handles missing file exceptions gracefully.
- Frontend Tests: Verify that the markdown container elements render cleanly and output appropriate empty-state notices if the payload content string is blank.