Release 0.5.0 documentation

[jk-lamb]

Pull Request

Description

This PR updates all documentation and prepares the release for Kanta v0.5.0, a minor version release that introduces Gettext 0.26+ and 1.0.0 compatibility through a custom backend adapter system. This release also includes stale message detection with fuzzy matching capabilities.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring
• Test improvements
• CI/CD improvements

Related Issues

Related to #100 - ISO639.json is too limited
Related to #108 - Base on Gettext 0.26
Related to #120 - Add option to remove translation keys that only exists on kanta__translations table
Related to #127 - Feature: Bump Gettext 1.0

Changes Made

Documentation Updates

• Updated README.md with comprehensive v0.5.0 documentation
• Reorganized documentation structure with proper heading hierarchy
• Added detailed sections for stale message detection and fuzzy matching
• Updated migration instructions with current versions (PostgreSQL v4, SQLite v3)
• Added separate database setup sections for PostgreSQL and SQLite
• Updated Gettext configuration instructions for v0.26+ backend system
• Added development and testing sections
• Reorganized image assets into assets/images/readme/ directory
• Added new screenshots for stale message features

CHANGELOG Updates

• Documented breaking changes for Gettext 1.0.0 migration
• Added all new features from v0.5.0 release
• Properly attributed contributors

Core Features Included in Documentation

• Gettext 0.26+ and 1.0.0 Compatibility: Custom backend adapter system (Kanta.Backend.Adapter.CachedDB)
• Stale Message Detection: Automatic detection of orphaned translations with fuzzy matching
• Custom Locale Support: Support for custom locale formats beyond ISO-639 (e.g., "es-es")
• Migration Path: Clear upgrade instructions for existing users

Testing

Test Environment

• Elixir version: 1.17-1.19
• OTP version: 27-28
• Phoenix version: 1.7.x and 1.8.x
• Database: PostgreSQL 15+ or SQLite 3.31.0+
• Gettext version: 0.26+ and 1.0.0

Test Cases

• All existing tests pass
• New tests added for new functionality at appropriate levels
• Manual testing performed

Test Commands Run

# Standard test suite
mix test

# Database setup and migration tests
MIX_ENV=test mix ecto.drop && MIX_ENV=test mix ecto.create && MIX_ENV=test mix ecto.migrate

# Code quality checks
mix format --check-formatted
mix credo
mix dialyzer

Documentation

• Updated README.md (major rewrite for v5.0)
• Updated documentation comments (comprehensive backend adapter docs)
• Updated CHANGELOG.md (v0.5.0 release notes)

Code Quality

• Code follows the existing style conventions
• Self-review of the code has been performed
• Code has been commented, particularly in hard-to-understand areas
• No new linting warnings introduced
• No new Dialyzer warnings introduced

Backward Compatibility

• This change is backward compatible
• This change includes breaking changes (please describe below)
• Migration guide provided for breaking changes

Security Considerations

• No security impact
• Security improvement
• Potential security impact (please describe)

Screenshots/Examples

N/A

Checklist

• I have read the Contributing Guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Reviewer Notes

N/A

[cursor]

Bug: ExDoc Main Option Case Mismatch

The main option for ExDoc is set to "readme" (lowercase), but the extras list contains "README.md". ExDoc typically expects the main option to match the basename of the file in the extras list, which should be "README" (uppercase) or remain as "Kanta" to reference the main module. This mismatch may cause ExDoc to fail to find the main page, depending on the version and case-sensitivity handling.