diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..499a4a9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,285 @@ +# CLAUDE.md - Repository Guidelines for Luminous + +This document defines the expectations, standards, and development practices for the Luminous project. All contributors (human and AI) should follow these guidelines. + +## Project Overview + +**Luminous** is a digital family command center designed for large, portrait-mounted touchscreens. It provides a calm, glanceable view of household schedules, tasks, and reminders. + +--- + +## Core Development Principles + +### 1. Programming Best Practices + +#### DRY (Don't Repeat Yourself) +- Extract repeated logic into reusable functions, components, or utilities +- Use shared constants and configuration files +- Create abstractions only when patterns emerge (Rule of Three) +- Prefer composition over inheritance + +#### SOLID Principles +- **S**ingle Responsibility: Each module/class/function should have one reason to change +- **O**pen/Closed: Open for extension, closed for modification +- **L**iskov Substitution: Subtypes must be substitutable for their base types +- **I**nterface Segregation: Many specific interfaces over one general-purpose interface +- **D**ependency Inversion: Depend on abstractions, not concretions + +#### Domain-Driven Design (DDD) +- Model the domain explicitly with ubiquitous language +- Separate domain logic from infrastructure concerns +- Use bounded contexts to define clear boundaries +- Implement aggregates, entities, and value objects appropriately +- Keep domain models pure and framework-agnostic + +#### Test-Driven Development (TDD) +- Write tests before implementation (Red-Green-Refactor) +- Each feature must have corresponding unit tests +- Integration tests for component interactions +- End-to-end tests for critical user journeys +- Maintain high test coverage without sacrificing test quality + +--- + +## Architecture Standards + +### Modular & Componentized Design + +All code must be: + +1. **Modular**: Self-contained units with clear boundaries +2. **Componentized**: UI elements as reusable, composable components +3. **Decoupled**: Minimal dependencies between modules +4. **Testable**: Easy to test in isolation + +#### Directory Structure Expectations + +``` +src/ +├── components/ # Reusable UI components +├── features/ # Feature-based modules (vertical slices) +├── domain/ # Domain models and business logic +├── services/ # External service integrations +├── hooks/ # Shared React hooks (if applicable) +├── utils/ # Pure utility functions +├── types/ # TypeScript type definitions +└── config/ # Configuration and constants +``` + +#### Component Guidelines + +- One component per file +- Co-locate component tests, styles, and stories +- Props should be typed and documented +- Avoid prop drilling; use context or state management appropriately +- Components should be presentational or container, not both + +--- + +## Documentation-Driven Design (DDD) + +### All New Features MUST Follow This Process + +1. **Write Documentation First** + - Create/update relevant documentation before writing code + - Define the feature's purpose, API, and expected behavior + - Include usage examples and edge cases + +2. **Design Review** + - Documentation serves as the design specification + - Review and iterate on the design before implementation + - Get stakeholder alignment through documentation + +3. **Implementation** + - Code to match the documented specification + - Update documentation if implementation reveals issues + +4. **Documentation Artifacts Required** + - README updates for user-facing features + - API documentation for new endpoints/interfaces + - Architecture Decision Records (ADRs) for significant decisions + - Inline code documentation for complex logic + +--- + +## Git Workflow & Commit Standards + +### Conventional Commits with Gitmoji + +All commits MUST follow the format: + +``` + (): + +[optional body] + +[optional footer(s)] +``` + +### Gitmoji Reference + +| Emoji | Code | Type | Description | +|-------|------|------|-------------| +| ✨ | `:sparkles:` | feat | New feature | +| 🐛 | `:bug:` | fix | Bug fix | +| 📝 | `:memo:` | docs | Documentation | +| 💄 | `:lipstick:` | style | UI/style updates | +| ♻️ | `:recycle:` | refactor | Code refactoring | +| ✅ | `:white_check_mark:` | test | Adding/updating tests | +| 🔧 | `:wrench:` | chore | Configuration/tooling | +| ⚡ | `:zap:` | perf | Performance improvement | +| 🔥 | `:fire:` | remove | Removing code/files | +| 🚀 | `:rocket:` | deploy | Deployment related | +| 🔒 | `:lock:` | security | Security fix | +| ⬆️ | `:arrow_up:` | deps | Upgrade dependencies | +| ⬇️ | `:arrow_down:` | deps | Downgrade dependencies | +| 🏗️ | `:building_construction:` | arch | Architectural changes | +| 🎨 | `:art:` | format | Code formatting | +| 🚧 | `:construction:` | wip | Work in progress | +| 💚 | `:green_heart:` | ci | CI/CD fixes | +| 🔊 | `:loud_sound:` | logs | Add/update logs | +| 🔇 | `:mute:` | logs | Remove logs | +| ♿ | `:wheelchair:` | a11y | Accessibility | +| 🌐 | `:globe_with_meridians:` | i18n | Internationalization | +| 📱 | `:iphone:` | responsive | Responsive design | + +### Scopes + +Use scopes to indicate the affected area: + +- `calendar` - Calendar-related changes +- `tasks` - Task/chore management +- `notes` - Notes and reminders +- `ui` - General UI components +- `display` - Display/kiosk mode +- `config` - Configuration +- `api` - API/backend changes +- `auth` - Authentication +- `db` - Database changes +- `infra` - Infrastructure + +### Commit Examples + +```bash +# Feature with scope +✨ feat(calendar): add week view navigation + +# Bug fix +🐛 fix(tasks): resolve task completion state not persisting + +# Documentation +📝 docs(readme): update installation instructions + +# Refactoring with scope +♻️ refactor(ui): extract button component from form + +# Tests +✅ test(calendar): add unit tests for date parsing + +# Breaking change (use footer) +💥 feat(api)!: redesign event response structure + +BREAKING CHANGE: Event objects now use ISO 8601 timestamps +``` + +--- + +## Code Quality Standards + +### Code Review Checklist + +- [ ] Follows DRY, SOLID, and DDD principles +- [ ] Includes appropriate tests +- [ ] Documentation updated +- [ ] No console.log or debug statements +- [ ] No hardcoded values (use constants/config) +- [ ] Accessible (WCAG 2.1 AA minimum) +- [ ] Performs well on target hardware +- [ ] Error handling is appropriate +- [ ] No security vulnerabilities introduced + +### Linting & Formatting + +- All code must pass linting without errors +- Use the project's configured formatter +- Pre-commit hooks enforce standards + +### Performance Considerations + +Given the always-on display nature of Luminous: + +- Minimize re-renders and DOM updates +- Avoid memory leaks (clean up subscriptions, timers) +- Optimize for 24/7 operation +- Test on target hardware specifications +- Keep bundle size minimal + +--- + +## Accessibility Requirements + +Luminous must be usable by all household members: + +- Support keyboard navigation +- Maintain proper focus management +- Use semantic HTML +- Provide sufficient color contrast +- Support screen readers where applicable +- Touch targets minimum 44x44 pixels +- Text readable from across the room + +--- + +## Security Guidelines + +- Never commit secrets, API keys, or credentials +- Validate all user input +- Sanitize displayed content +- Use HTTPS for all external communications +- Follow OWASP guidelines +- Regular dependency audits + +--- + +## Build & Development Commands + +```bash +# Install dependencies +npm install + +# Run development server +npm run dev + +# Run tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Build for production +npm run build + +# Lint code +npm run lint + +# Format code +npm run format + +# Type check +npm run typecheck +``` + +--- + +## Getting Help + +- Check existing documentation first +- Search closed issues for similar problems +- Open a discussion for questions +- File an issue for bugs with reproduction steps + +--- + +## License + +This project is licensed under AGPL-3.0. All contributions must be compatible with this license. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..88d71a7 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,121 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in the Luminous community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- **Demonstrating empathy and kindness** toward other people +- **Being respectful** of differing opinions, viewpoints, and experiences +- **Giving and gracefully accepting** constructive feedback +- **Accepting responsibility** and apologizing to those affected by our mistakes, and learning from the experience +- **Focusing on what is best** not just for us as individuals, but for the overall community +- **Using welcoming and inclusive language** +- **Being patient** with newcomers and those learning + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Sustained disruption of community events, forums, or discussions +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Scope + +This Code of Conduct applies within all community spaces, including: + +- GitHub repositories (issues, pull requests, discussions, code reviews) +- Community chat channels or forums +- Project events and meetups +- Social media interactions related to the project +- Any other spaces where individuals represent the project + +This Code of Conduct also applies when an individual is officially representing the community in public spaces. + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, or reject: + +- Comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct +- Contributors who violate this Code of Conduct, temporarily or permanently + +## Reporting + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers responsible for enforcement. + +When reporting, please provide: + +- Your contact information +- Names (usernames) of any individuals involved +- Description of the behavior +- Date and location (links) where the behavior occurred +- Any additional context or screenshots + +All reports will be reviewed and investigated promptly and fairly. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. + +## Enforcement Guidelines + +Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from project maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Acknowledgment of Family Focus + +Luminous is designed for families, including children. We take special care to ensure that all project communications and contributions are appropriate for all ages. Contributors should be mindful that: + +- Discussions and comments may be read by people of all ages +- The project's mission is to support household harmony +- Interactions should model the calm, respectful environment we aim to create + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][mozilla]. + +For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][faq]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla]: https://github.com/mozilla/diversity +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + +--- + +## Summary + +Be kind. Be respectful. Be helpful. + +This project exists to make households run more smoothly. Let's build that same spirit of cooperation and mutual respect in our community. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..40fa8f8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,356 @@ +# Contributing to Luminous + +Thank you for your interest in contributing to Luminous! This document provides guidelines and information for contributors. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Process](#development-process) +- [Pull Request Process](#pull-request-process) +- [Style Guidelines](#style-guidelines) +- [Community](#community) + +--- + +## Code of Conduct + +This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. + +--- + +## How Can I Contribute? + +### Reporting Bugs + +Before creating a bug report, please check existing issues to avoid duplicates. + +When filing a bug report, include: + +- **Clear title** describing the issue +- **Steps to reproduce** the behavior +- **Expected behavior** vs. actual behavior +- **Screenshots or recordings** if applicable +- **Environment details**: + - OS and version + - Display size and resolution + - Browser/runtime version + - Hardware specifications + +Use this template: + +```markdown +## Bug Description +A clear description of what the bug is. + +## Steps to Reproduce +1. Go to '...' +2. Click on '...' +3. Scroll down to '...' +4. See error + +## Expected Behavior +What you expected to happen. + +## Actual Behavior +What actually happened. + +## Screenshots +If applicable, add screenshots. + +## Environment +- OS: [e.g., Ubuntu 22.04] +- Display: [e.g., 27" 1080x1920 portrait] +- Node version: [e.g., 20.10.0] +- Browser: [e.g., Chromium 120] +``` + +### Suggesting Features + +We welcome feature suggestions! Before suggesting: + +1. Check if the feature aligns with our [Design Principles](README.md#design-principles) +2. Search existing issues and discussions +3. Consider if it benefits the typical household use case + +When suggesting a feature: + +- **Describe the problem** you're trying to solve +- **Explain your proposed solution** +- **Consider alternatives** you've thought about +- **Provide examples** or mockups if possible + +### Contributing Code + +We especially welcome contributions in these areas: + +- UI/UX improvements for large portrait displays +- Accessibility enhancements +- Reliability and startup hardening +- Documentation and setup guides +- Performance optimizations +- Test coverage improvements + +--- + +## Development Process + +### 1. Fork and Clone + +```bash +# Fork the repository on GitHub, then: +git clone https://github.com/YOUR_USERNAME/Luminous.git +cd Luminous +git remote add upstream https://github.com/trickpatty/Luminous.git +``` + +### 2. Create a Branch + +Branch names should be descriptive: + +```bash +# Feature +git checkout -b feature/calendar-week-view + +# Bug fix +git checkout -b fix/task-completion-state + +# Documentation +git checkout -b docs/setup-guide + +# Refactoring +git checkout -b refactor/component-extraction +``` + +### 3. Development Workflow + +Follow **Documentation-Driven Design**: + +1. **Document First**: Write or update documentation for your change +2. **Write Tests**: Create tests that define expected behavior (TDD) +3. **Implement**: Write code to pass the tests +4. **Refactor**: Clean up while keeping tests green +5. **Review**: Self-review against our standards + +### 4. Commit Your Changes + +Follow [Conventional Commits with Gitmoji](CLAUDE.md#git-workflow--commit-standards): + +```bash +# Good commits +✨ feat(calendar): add week view navigation +🐛 fix(tasks): resolve completion state persistence +📝 docs(contributing): add development workflow section +✅ test(calendar): add unit tests for date utilities + +# Bad commits (avoid these) +"fixed stuff" +"WIP" +"updates" +``` + +### 5. Keep Your Branch Updated + +```bash +git fetch upstream +git rebase upstream/main +``` + +### 6. Push and Create PR + +```bash +git push origin your-branch-name +``` + +Then create a Pull Request on GitHub. + +--- + +## Pull Request Process + +### Before Submitting + +Ensure your PR: + +- [ ] Follows the [style guidelines](#style-guidelines) +- [ ] Includes tests for new functionality +- [ ] Updates relevant documentation +- [ ] Passes all existing tests +- [ ] Has no linting errors +- [ ] Includes a clear description + +### PR Template + +```markdown +## Description +Brief description of changes. + +## Type of Change +- [ ] Bug fix (non-breaking change fixing an issue) +- [ ] New feature (non-breaking change adding functionality) +- [ ] Breaking change (fix or feature causing existing functionality to change) +- [ ] Documentation update +- [ ] Refactoring (no functional changes) + +## Related Issues +Fixes #(issue number) + +## How Has This Been Tested? +Describe the tests you ran. + +## Checklist +- [ ] My code follows the project style guidelines +- [ ] I have performed a self-review +- [ ] I have commented complex code +- [ ] I have updated documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests proving my fix/feature works +- [ ] New and existing tests pass locally +- [ ] Any dependent changes have been merged +``` + +### Review Process + +1. **Automated Checks**: CI must pass +2. **Code Review**: At least one maintainer review required +3. **Documentation Review**: Ensure docs are updated +4. **Testing**: Verify on representative hardware if possible + +### After Merge + +- Delete your branch +- Update your fork's main branch +- Celebrate your contribution! 🎉 + +--- + +## Style Guidelines + +### Code Standards + +Please refer to [CLAUDE.md](CLAUDE.md) for detailed coding standards including: + +- DRY, SOLID, and DDD principles +- Modular and componentized architecture +- Testing requirements +- Accessibility standards + +### Commit Messages + +Use Conventional Commits with Gitmoji: + +``` + (): + +[optional body] + +[optional footer(s)] +``` + +See [CLAUDE.md - Commit Standards](CLAUDE.md#git-workflow--commit-standards) for the complete reference. + +### Documentation Style + +- Use clear, concise language +- Include code examples where helpful +- Keep the target audience in mind (household users, developers) +- Use proper Markdown formatting +- Add screenshots for UI-related documentation + +### Code Formatting + +- Follow the project's linting configuration +- Run formatters before committing +- Use meaningful variable and function names +- Keep functions focused and small +- Comment complex logic, not obvious code + +--- + +## Testing Guidelines + +### Test Requirements + +All contributions should include appropriate tests: + +- **Unit Tests**: For individual functions and components +- **Integration Tests**: For feature workflows +- **Accessibility Tests**: For UI components +- **Visual Tests**: For UI changes (if applicable) + +### Running Tests + +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run tests with coverage +npm run test:coverage + +# Run specific test file +npm test -- path/to/test +``` + +### Writing Good Tests + +```javascript +// Good test example +describe('TaskList', () => { + describe('when marking a task complete', () => { + it('should update the task status', () => { + // Arrange + const task = createTask({ status: 'pending' }); + + // Act + const result = markComplete(task); + + // Assert + expect(result.status).toBe('completed'); + }); + + it('should record the completion timestamp', () => { + // ... + }); + }); +}); +``` + +--- + +## Community + +### Getting Help + +- **Questions**: Open a GitHub Discussion +- **Bugs**: Open a GitHub Issue +- **Features**: Open a GitHub Discussion first + +### Recognition + +Contributors are recognized in: + +- The project's contributors list +- Release notes for significant contributions +- Special acknowledgments for major features + +--- + +## License Agreement + +By contributing to Luminous, you agree that your contributions will be licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. + +This means: +- Your contributions remain open source +- Derivative works must also be open source +- The community benefits from all improvements + +--- + +## Thank You! + +Every contribution makes Luminous better for families everywhere. Whether it's fixing a typo, improving documentation, or adding a major feature — we appreciate your time and effort. + +Together, we're building a calmer way for households to stay connected.