Skip to content

docs: add decision records for custom implementations vs FOSS libraries

Greeshma Kanukunta requested to merge docs/foss-decision-records into develop

Overview

This MR adds decision record comments for custom implementations used in the codebase instead of existing FOSS libraries. It improves maintainability by documenting the rationale behind these decisions, helping future contributors understand trade-offs and avoid redundant rewrites.

What does this MR do and why?

Previously, several parts of the project used custom implementations without documenting why established FOSS libraries were not adopted. This lack of context can lead to confusion, duplication of effort, or incorrect refactoring.

This MR addresses that gap by:

  • Adding inline decision record comments in key files
  • Explaining the reasoning behind choosing custom implementations
  • Highlighting trade-offs and future considerations

The approach was to use inline comments instead of separate ADR files to keep documentation close to the code for better visibility and ease of maintenance.

Changes Made

  • Added decision record comments in:
    • src/contexts/ThemeContext.tsx
    • src/utils/searchUtils.ts
    • src/lib/utils.ts (formatToIST)
    • src/contexts/AuthContext.tsx

Technical Details

  • No functional or logic changes were made
  • Comments include:
    • Custom implementation details
    • Alternative libraries (e.g., next-themes, Fuse.js, date-fns-tz)
    • Reasons for current approach
    • Trade-offs and future considerations
  • Comments are placed near relevant implementations for clarity

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 💥 Breaking change (fix or feature that would cause existing functionality to change)
  • 📝 Documentation update
  • 🎨 UI/UX improvement
  • ♻️ Refactor (no functional changes)
  • ⚡ Performance improvement
  • 🧪 Test update
  • 🔧 Configuration change
  • 🚨 Security fix

Related Issues / References

Closes #253 (closed)

Screenshots or Screen Recordings

Not applicable (documentation-only change)

How to Set Up and Validate Locally

  1. Switch to the branch: git checkout docs/foss-decision-records

  2. Install dependencies: bun install

  3. Run the development server: bun dev

Verify

  • Open the modified files
  • Confirm decision record comments are present
  • Ensure no functional changes in application behavior

Testing Done

  • Manual testing completed
  • No unit tests required (documentation-only change)

Test Cases Covered

Scenario Expected Result Status
Application runs normally No runtime errors ✅
Files updated Comments visible ✅
Functionality unchanged No behavior changes ✅

Code Quality Checklist

Code Standards

  • Code follows project conventions
  • No console.log() or debugger statements
  • No unused imports or variables
  • No duplicate code
  • i18n check passed
  • TypeScript types properly defined
  • ESLint and Prettier checks pass

React Best Practices

  • No functional changes affecting components or hooks

Component Patterns

  • No UI/component changes introduced

API & Data Fetching

  • No API changes

Error Handling

  • No impact on error handling

Documentation

  • README.md updated
  • .env.example updated
  • CHANGELOG.md updated

Known Limitations / Technical Debt

  • Decision records are currently inline comments only
  • Future improvement: Consider adding structured ADRs in docs/decisions/ for scalability

Additional Notes

This change ensures that future contributors understand the reasoning behind architectural decisions and encourages consistent evaluation of FOSS libraries before implementing custom solutions.

MR Acceptance Checklist

Evaluate this MR against the GitLab MR acceptance checklist.

Edited by Greeshma Kanukunta

Merge request reports