# Contributing to ReadMeABook Thank you for your interest in contributing to ReadMeABook! This document provides guidelines and instructions for contributing to the project. --- ## ๐Ÿค How to Contribute ### Reporting Issues If you encounter a bug or have a feature request: 1. **Check existing issues** - Search [GitHub Issues](https://github.com/kikootwo/ReadMeABook/issues) to see if it's already reported 2. **Create a new issue** - Use the appropriate issue template 3. **Provide details** - Include: - Clear description of the problem/feature - Steps to reproduce (for bugs) - Expected vs actual behavior - Environment details (OS, Docker version, etc.) - Relevant logs or screenshots ### Submitting Pull Requests 1. **Fork the repository** 2. **Create a feature branch** from `main`: ```bash git checkout -b feature/your-feature-name ``` 3. **Make your changes** following our coding standards 4. **Test your changes** thoroughly 5. **Commit with clear messages**: ```bash git commit -m "Add: brief description of changes" ``` 6. **Push to your fork**: ```bash git push origin feature/your-feature-name ``` 7. **Open a Pull Request** with: - Clear title and description - Reference to related issues - Screenshots/demos if applicable --- ## ๐Ÿ—๏ธ Development Setup ### Prerequisites - Node.js 20+ - Docker & Docker Compose - Git ### Local Development 1. **Clone the repository:** ```bash git clone https://github.com/kikootwo/ReadMeABook.git cd ReadMeABook ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Set up environment:** ```bash cp .env.example .env # Edit .env with your local configuration ``` 4. **Start development stack:** ```bash # Using Docker Compose (recommended) docker compose -f docker-compose.local.yml up -d # Or run services separately docker compose -f docker-compose.debug.yml up -d postgres redis npm run dev ``` 5. **Run database migrations:** ```bash npm run prisma:generate npm run db:push ``` 6. **Access the app:** - App: http://localhost:3030 - Prisma Studio: `npm run prisma:studio` --- ## ๐Ÿ“ Coding Standards ### General Guidelines - **Follow existing code style** - Use the project's ESLint configuration - **Write clear, descriptive variable names** - **Add comments for complex logic** - **Keep functions small and focused** - **Test your changes** ### TypeScript - Use TypeScript for all new code - Define proper types (avoid `any`) - Use interfaces for object shapes - Export types when they're reusable ### React Components - Use functional components with hooks - Keep components focused and reusable - Use proper TypeScript props typing - Follow the existing component structure in `src/components/` ### File Organization - **Max 300-400 lines per file** - Refactor if larger - **Add file headers** to reference documentation: ```typescript /** * Component: Feature Name * Documentation: documentation/path/to/doc.md */ ``` ### Database Changes - Always use Prisma migrations - Test migrations with seed data - Document schema changes in pull request --- ## ๐Ÿ“š Documentation ### Updating Documentation When making changes that affect documentation: 1. **Update relevant docs** in `documentation/` 2. **Use token-efficient format** (see [CLAUDE.md](CLAUDE.md)) 3. **Update TABLEOFCONTENTS.md** if adding new docs 4. **Keep docs in sync** with code changes ### Documentation Standards - Use bullet points over prose - Include code examples where helpful - Keep status indicators updated (โœ…/โณ/โŒ) - Link to related documentation --- ## ๐Ÿงช Testing ### Before Submitting - Test locally with Docker Compose - Verify no console errors - Test with clean database (migrations) - Check responsive design (if UI changes) - Verify all features still work ### Manual Testing Checklist - [ ] Login with Plex works - [ ] Library scan completes - [ ] Book requests can be created - [ ] Settings can be updated - [ ] Background jobs run correctly --- ## ๐Ÿ” Code Review Process ### What We Look For - **Functionality** - Does it work as intended? - **Code quality** - Is it clean and maintainable? - **Testing** - Has it been adequately tested? - **Documentation** - Are docs updated? - **Breaking changes** - Are they necessary and documented? ### Review Timeline - Initial review: Within 1-2 weeks - Follow-up on feedback: Ongoing - Merge: When approved and CI passes --- ## ๐Ÿš€ Release Process ### Versioning We follow [Semantic Versioning](https://semver.org/): - **MAJOR**: Breaking changes - **MINOR**: New features (backward compatible) - **PATCH**: Bug fixes ### Release Cycle - Releases are tagged as needed - Docker images automatically built on push to `main` - Breaking changes documented in release notes --- ## ๐Ÿ’ก Development Tips ### Working with Prisma ```bash # Generate Prisma client after schema changes npm run prisma:generate # Push schema changes to database npm run db:push # Open Prisma Studio npm run prisma:studio ``` ### Working with Docker ```bash # Build local image docker compose -f docker-compose.local.yml build # View logs docker compose -f docker-compose.local.yml logs -f # Reset database docker compose -f docker-compose.local.yml down -v ``` ### Debugging - Use `LOG_LEVEL=debug` in environment - Check browser console for frontend issues - Use Prisma Studio to inspect database - Check Docker logs for backend issues --- ## ๐Ÿ“‹ Commit Message Guidelines ### Format ``` :