Skip to content

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

  1. Read the physical file content from the project root /CHANGELOG.md using the file system utility (fs.readFileSync or standard runtime equivalent).
  2. Error Handling: If the file is missing or unreadable, return a structured HTTP 404 or an empty fallback template instead of crashing the process.
  3. 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.
  4. Return the raw text string inside a JSON payload: { content: string }.

๐ŸŽจ 3. User Interface (apps/web) โ€‹

Route: /changelog

  1. Fetch data from GET /api/changelog on component mount or server render.
  2. Use a standard markdown parsing utility (e.g., react-markdown combined with typography styles like @tailwindcss/typography) to render the text.
  3. 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.