booklore/CONTRIBUTING.md

Contributing to Booklore

🎉 Thank you for your interest in contributing to Booklore! Whether you're fixing bugs, adding features, improving documentation, or simply asking questions, every contribution helps make Booklore better for everyone.

---

📚 What is Booklore?

Booklore is a modern, self-hostable digital library platform for managing and reading books and comics. It's designed with privacy, flexibility, and ease of use in mind.

Tech Stack:

• Frontend: Angular 20, TypeScript, PrimeNG 19
• Backend: Java 21, Spring Boot 3.5
• Authentication: Local JWT + optional OIDC (e.g., Authentik)
• Database: MariaDB
• Deployment: Docker-compatible, reverse proxy-ready

---

📦 Project Structure

booklore/
├── booklore-ui/           # Angular frontend application
├── booklore-api/          # Spring Boot backend API
├── assets/                # Shared assets (logos, icons, etc.)
├── docker-compose.yml     # Production Docker setup
└── dev.docker-compose.yml # Development Docker setup

---

🚀 Getting Started

1. Fork and Clone

First, fork the repository to your GitHub account, then clone it locally:

# Clone your fork
git clone https://github.com/<your-username>/booklore.git
cd booklore

# Add upstream remote to keep your fork in sync
git remote add upstream https://github.com/booklore-app/booklore.git

2. Keep Your Fork Updated

Before starting work on a new feature or fix:

# Fetch latest changes from upstream
git fetch upstream

# Merge upstream changes into your local main branch
git checkout main
git merge upstream/main

# Push updates to your fork
git push origin main

---

🧱 Local Development Setup

Booklore offers two development approaches: an all-in-one Docker stack for quick setup, or manual installation for more control.

Option 1: Docker Development Stack (Recommended for Quick Start)

This option sets up everything with a single command:

docker compose -f dev.docker-compose.yml up

What you get:

• ✅ Frontend dev server at http://localhost:4200/
• ✅ Backend API at http://localhost:8080/
• ✅ MariaDB at localhost:3366
• ✅ Remote Java debugging at localhost:5005

Note: All ports are configurable via environment variables in dev.docker-compose.yml:

• FRONTEND_PORT (default: 4200)
• BACKEND_PORT (default: 8080)
• DB_PORT (default: 3366)
• REMOTE_DEBUG_PORT (default: 5005)

Stopping the stack:

docker compose -f dev.docker-compose.yml down

---

Option 2: Manual Local Development

For more control over your development environment, you can run each component separately.

Prerequisites

Ensure you have the following installed:

• Java 21+ (Download)
• Node.js 18+ and npm (Download)
• MariaDB 10.6+ (Download)
• Git (Download)

Frontend Setup

# Navigate to the frontend directory
cd booklore-ui

# Install dependencies
npm install

# Start the development server
ng serve

# Or use npm script
npm start

The frontend will be available at http://localhost:4200/ with hot-reload enabled.

Common Issues:

• If you encounter dependency conflicts, try npm install --legacy-peer-deps
• Use --force only as a last resort

---

Backend Setup

Step 1: Configure Application Properties

Create a development configuration file at booklore-api/src/main/resources/application-dev.yml:

app:
  # Path where books and comics are stored
  path-book: '/Users/yourname/booklore-data/books'
  
  # Path for thumbnails, metadata cache, and other config files
  path-config: '/Users/yourname/booklore-data/config'

spring:
  datasource:
    driver-class-name: org.mariadb.jdbc.Driver
    url: jdbc:mariadb://localhost:3306/booklore?createDatabaseIfNotExist=true
    username: root
    password: your_secure_password

Important:

• Replace /Users/yourname/... with actual paths on your system
• Create these directories if they don't exist
• Ensure proper read/write permissions

Example paths:

• macOS/Linux: /Users/yourname/booklore-data/books
• Windows: C:\Users\yourname\booklore-data\books

Step 2: Set Up the Database

Ensure MariaDB is running and create the database:

# Connect to MariaDB
mysql -u root -p

# Create database and user (optional)
CREATE DATABASE IF NOT EXISTS booklore;
CREATE USER 'booklore_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON booklore.* TO 'booklore_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Run the Backend

cd booklore-api
./gradlew bootRun --args='--spring.profiles.active=dev'

The backend API will be available at http://localhost:8080/

Verify it's running:

curl http://localhost:8080/actuator/health

---

🧪 Testing

Always run tests before submitting a pull request to ensure your changes don't break existing functionality.

Backend Tests

cd booklore-api

# Run all tests
./gradlew test

# Run tests with detailed output
./gradlew test --info

# Run a specific test class
./gradlew test --tests "com.booklore.api.service.BookServiceTest"

# Generate coverage report
./gradlew test jacocoTestReport

Before creating a PR, always run:

./gradlew test

---

🛠️ Contributing Guidelines

💡 Reporting Bugs

Found a bug? Help us fix it by providing detailed information:

1. Search existing issues to avoid duplicates
2. Create a new issue with the bug label
3. Include the following:
   • Clear, descriptive title (e.g., "Book import fails with PDF files over 100MB")
   • Steps to reproduce the issue
   • Expected behavior vs. actual behavior
   • Screenshots or error logs if applicable
   • Your environment (OS, browser, Docker version, etc.)

Example Bug Report:

**Title:** Book metadata not updating after manual edit

**Description:**
When I manually edit a book's metadata through the UI and click Save, 
the changes appear to save but revert after page refresh.

**Steps to Reproduce:**
1. Navigate to any book detail page
2. Click "Edit Metadata"
3. Change the title from "Old Title" to "New Title"
4. Click "Save"
5. Refresh the page

**Expected:** Title should remain "New Title"
**Actual:** Title reverts to "Old Title"

**Environment:**
- Browser: Chrome 120
- OS: macOS 14.2
- Booklore Version: 1.2.0

---

🔃 Submitting Code Changes

Branch Naming Convention

Create descriptive branches that clearly indicate the purpose of your changes:

# For new features
git checkout -b feat/add-dark-mode-theme
git checkout -b feat/epub-reader-support

# For bug fixes
git checkout -b fix/book-import-validation
git checkout -b fix/memory-leak-in-scanner

# For documentation
git checkout -b docs/update-installation-guide

# For refactoring
git checkout -b refactor/improve-authentication-flow

Development Workflow

1. Create a branch from develop (not main)
2. Make your changes in small, logical commits
3. Test thoroughly - run both frontend and backend tests
4. Update documentation if your changes affect usage
5. Run the linter and fix any issues
6. Commit with clear messages following Conventional Commits
7. Push to your fork
8. Open a pull request targeting the develop branch

Pull Request Checklist

Before submitting, ensure:

• Code follows project conventions
• All tests pass (./gradlew test for backend)
• IntelliJ linter shows no errors
• Changes are documented (README, inline comments)
• PR description clearly explains what and why
• PR is linked to a related issue (if applicable)
• Branch is up-to-date with develop
• For big features: Create a documentation PR at booklore-docs with styling similar to other documentation pages

---

🧼 Code Style & Conventions

• Angular: Follow the official style guide
• Java: Use modern features (Java 21), clean structure
• Linter: Use IntelliJ IDEA's built-in linter for code formatting and style checks
• UI: Use SCSS and PrimeNG components consistently

---

📝 Commit Message Format

We follow Conventional Commits for clear, standardized commit messages.

Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks
• perf: Performance improvements

Examples

# Feature addition
feat(reader): add keyboard navigation for page turning

# Bug fix
fix(api): resolve memory leak in book scanning service

# Documentation
docs(readme): add troubleshooting section for Docker setup

# Multiple scopes
feat(api,ui): implement book collection management

# Breaking change
feat(auth)!: migrate to OAuth 2.1

BREAKING CHANGE: OAuth 2.0 is no longer supported

---

🙏 Code of Conduct

We're committed to providing a welcoming and inclusive environment for everyone.

Our Standards:

• ✅ Be respectful and considerate
• ✅ Welcome newcomers and help them learn
• ✅ Accept constructive criticism gracefully
• ✅ Focus on what's best for the community

Unacceptable Behavior:

• ❌ Harassment, trolling, or discrimination
• ❌ Personal attacks or insults
• ❌ Publishing others' private information
• ❌ Any conduct that would be inappropriate in a professional setting

Enforcement: Instances of unacceptable behavior may result in temporary or permanent ban from the project.

---

💬 Community & Support

Need help or want to discuss ideas?

• 💬 Discord: Join our server
• 🐛 Issues: GitHub Issues

---

📄 License

Booklore is open-source software licensed under the GPL-3.0 License.

By contributing, you agree that your contributions will be licensed under the same license. See the LICENSE file for full details.

---

🎯 What to Work On?

Not sure where to start? Check out:

• Issues labeled good first issue
• Issues labeled help wanted
• Our project roadmap

---

🎉 Thank You!

Every contribution, no matter how small, makes Booklore better. Thank you for being part of our community!

Happy Contributing! 📚✨