Skip to content

CHANGELOG.md

Latest commit

 

History

History
219 lines (165 loc) · 8.56 KB

CHANGELOG.md

File metadata and controls

219 lines (165 loc) · 8.56 KB
Raw

Changelog — EmberDocs

All notable changes to EmberDocs are documented in this file. The format follows Keep a Changelog, and this project adheres to Semantic Versioning.

Format: For each release, document Added, Changed, Deprecated, Removed, Fixed, and Security sections.

[Unreleased]

Added

  • Sidebar navigation component with nested expand/collapse and active page indicators
  • VersionSwitcher modal component for Git-tag based version selection
  • NavigationFooter component with prev/next document links
  • Navigation helpers library (nav-helpers.ts) for document traversal
  • Component unit tests for SearchPalette, ThemeToggle, Breadcrumbs, TableOfContents (18 new test cases)
  • IntersectionObserver mock in Jest setup for improved component testing
  • React-markdown integration for Markdown rendering with GitHub-flavored Markdown support

Changed

  • Refactored doc page layout from 2-column to 3-column grid (sidebar + content + TOC)
  • Migrated markdown rendering from custom regex-based logic to react-markdown
  • Improved CodeBlock component to support optional syntax highlighting
  • Header component now accepts optional versions prop for VersionSwitcher
  • Updated doc page component to use shared parseMarkdown from lib instead of duplicate logic
  • Search palette open state is managed by the docs layout; SearchPalette now accepts isOpen, onClose, and onToggle props

Fixed

  • Fixed XSS vulnerability in markdown rendering (eliminated dangerouslySetInnerHTML without sanitization)
  • Fixed DRY violation with duplicate markdown parsing logic in doc page component
  • Fixed CodeBlock TypeScript prop type issues with optional highlightedHtml
  • Fixed search palette opening issues (header button and Cmd+K/Ctrl+K)
  • Fixed search palette styling and alignment to match the search modal mockup
  • Improved test coverage from 50.57% to 64.11% overall

Security

  • Eliminated XSS vulnerability by replacing unsafe custom HTML renderer with react-markdown
  • Removed duplicate markdown parsing that could diverge from tested implementation
  • All markdown content now properly sanitized through react-markdown component

Removed

  • Deleted unused performance monitoring module (src/lib/performance.ts, 0% coverage)
  • Removed custom renderMarkdown function (replaced with react-markdown)
  • Removed custom parseMarkdown function from doc page (now using lib version)
  • Removed SearchContext in favor of a simpler props-based search palette implementation

[0.1.0-beta] — TBD (Phase 02 Complete)

MVP Phase 02: Stabilization

Target Release: After 6-week MVP development + beta feedback period (4–8 weeks)

Added

  • Error Handling: Error boundaries with user-friendly messages for parse failures, missing files, invalid frontmatter
  • Accessibility: WCAG 2.1 Level AA compliance (keyboard navigation, ARIA labels, color contrast ≥ 4.5:1)
  • Performance Monitoring: Web Vitals tracking (LCP, FID, CLS) with console logging and hooks for external APM
  • Version Detection: Git tag-based version routing (/docs/v1.0/guide, /docs/main/guide)
  • Version Switcher UI: Header dropdown to select available document versions
  • Documentation: Expanded user guides (setup, deployment, configuration, troubleshooting), developer guides (architecture deep dives)
  • Changelog: This changelog documenting all releases

Changed

  • Phase 01 Deliverables: Enhanced phase plan with detailed deliverables (D1.1–D1.9), weekly milestones, success metrics
  • Phase 02 Deliverables: Enhanced phase plan with detailed deliverables (D2.1–D2.9), exit criteria, risk mitigations
  • Architecture Decisions: Formalized ADL (Architecture Decision Log) with 7 key decisions and rationale

Fixed

  • Beta testing will identify issues; documented in post-release updates

Security

  • No breaking security changes; env-flagged integrations enable safe optional features

[0.1.0-alpha] — 2025-12-23 (Phase 01 Complete)

MVP Phase 01: Core Engine

This is the first alpha release containing core authoring, navigation, and search functionality.

Added

  • Next.js 16 App Router: TypeScript-first, strict mode, path aliases (@/* → src/*)
  • Content Pipeline: Markdown/MDX parsing with YAML frontmatter, TOC generation, syntax highlighting (Shiki/Prism)
  • Navigation Generation: Auto-generated sidebar from file structure with breadcrumb support
  • Client-Side Search: FlexSearch index pre-built at build time, <50ms query performance, ⌘K command palette
  • Theming: Dark theme-first with light theme opt-in, CSS variables, Tailwind CSS configuration
  • Responsive UI: Components for doc pages, nav, search, theme toggle; mobile-friendly (375px–1920px)
  • Build Tooling: npm run dev, npm run build, npm run lint, npm run typecheck, npm run test
  • GitHub Actions CI: Automated lint → typecheck → test → build on PR/push
  • Documentation: Technical spec, database schema, API spec, roadmap, contributor guides
  • Contributor Guidelines: AGENTS.md, claude.md, .cursorrules (synced across all three)
  • Sample Content: 5–10 example docs in docs/examples/ for testing
  • Test Suite: Jest unit tests for content parsing, search indexing, navigation generation; basic smoke tests

Changed

  • Initial release; no prior versions

Fixed

  • N/A for alpha release

Security

  • No known security issues; privacy-first architecture (no external SaaS for core features)

Known Issues (Defer to Phase 02)

  • Accessibility audit needed (defer detailed WCAG audit to Phase 02)
  • Playwright end-to-end tests not yet implemented (will add in Phase 02)
  • Version detection/routing not yet implemented (planned for Phase 02)
  • Changelog and release notes automation needed (will improve in Phase 02)

Testing Notes

  • CI passes: lint ✅, typecheck ✅, tests ✅ (coverage ≥ 70%)
  • Build time: ~30s for 1000 sample docs
  • Search performance: <50ms for typical queries
  • Lighthouse scores: accessibility ~90, performance ~85 (detailed audit deferred to Phase 02)
  • Mobile responsive: verified on 375px, 768px, 1280px breakpoints

Thanks

  • Thank you to early contributors and feedback providers!

Release Template (Copy for New Releases)

## [X.Y.Z] — YYYY-MM-DD

### Added
- Feature 1
- Feature 2

### Changed
- Change 1
- Change 2

### Deprecated
- Deprecated feature (will be removed in vX.Y+1)

### Removed
- Removed feature (with migration guide if applicable)

### Fixed
- Bug fix 1
- Bug fix 2

### Security
- Security patch 1 (CVE-XXXX-XXXXX if applicable)

### Known Issues
- [ ] Known issue 1
- [ ] Known issue 2

### Testing Notes
- Test coverage: X%
- CI status: passing
- Browser compatibility: tested on Chrome, Firefox, Safari, Edge
- Mobile: tested on iPhone 12, Android 12

### Contributors
- @username1
- @username2

Versioning Scheme

EmberDocs uses Semantic Versioning: MAJOR.MINOR.PATCH

  • MAJOR (0 → 1): Breaking changes (migration guide required)
  • MINOR (0 → 1): New features, backward compatible
  • PATCH (0 → 1): Bug fixes, no new features

Pre-Release Versions

  • 0.1.0-alpha.1 — Unstable, feature-incomplete
  • 0.1.0-beta.1 — Feature-complete, may have bugs
  • 1.0.0-rc.1 — Release candidate, ready for final testing

Version Tags in Git

# Create a release tag
git tag -a v0.1.0-alpha -m "MVP Phase 01: Core engine"
git tag -a v0.1.0-beta -m "MVP Phase 02: Stabilization"
git tag -a v1.0.0 -m "General availability release"

# Push tags to remote
git push origin --tags

Changelog Maintenance Guidelines

When to Update

  • ✅ For each commit/PR: update [Unreleased] section with changes
  • ✅ When releasing: move [Unreleased] to [X.Y.Z] — YYYY-MM-DD

What to Include

  • ✅ New features and enhancements (user-facing)
  • ✅ Breaking changes with migration notes
  • ✅ Bug fixes (group by feature or component)
  • ✅ Security patches with CVE references
  • ⚠️ Refactoring, internal restructuring (only if significant)
  • ❌ Internal code style changes, linting improvements (omit unless major)

Linking to Issues/PRs

- Fixed search index size growing unbounded (#42, #51)
- Added version switching UI ([PR #123](https://github.com/sturdy-barnacle/emberdocs/pull/123))

Review Checklist

  • Changelog updated before release
  • Version number bumped in package.json
  • Git tag created (e.g., v0.1.0-beta)
  • Release notes published (GitHub Releases)
  • Announcement sent (email, Slack, Twitter if applicable)