booklore-app/booklore
1
0
Fork 0
mirror of https://github.com/booklore-app/booklore.git synced 2026-02-17 16:07:55 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: clean up PR template and contributing guide (#2660)

Browse Source 
Co-authored-by: acx10 <acx10@users.noreply.github.com>
This commit is contained in:
ACX
2026-02-08 12:13:34 -07:00
committed by GitHub
parent 108d94c0f7
commit c1202ea476
2 changed files with 254 additions and 355 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
.github/pull_request_template.md vendored
View File

@@ -1,59 +1,55 @@
## 🚀 Pull Request
## 📝 Description
### 📝 Description
<!-- Why is this change needed? Link related issues (e.g. Fixes #123) -->
<!-- Provide a clear and concise summary of the changes introduced in this pull request -->
<!-- Reference related issues using "Fixes #123", "Closes #456", or "Relates to #789" -->
## 🏷️ Type of Change
### 🛠️ Changes Implemented
- [ ] Bug fix
- [ ] New feature
- [ ] Enhancement to existing feature
- [ ] Refactor (no behavior change)
- [ ] Breaking change (existing functionality affected)
- [ ] Documentation update
<!-- Detail the specific modifications, additions, or removals made in this pull request -->
-
## 🔧 Changes
### 🧪 Testing Strategy
<!-- List the specific modifications made -->
-
<!-- Describe the testing methodology used to verify the correctness of these changes -->
<!-- Include testing approach, scenarios covered, and edge cases considered -->
## 🧪 Testing
### 📸 Visual Changes _(if applicable)_
<!-- What did you test? What edge cases did you cover? What could still break? -->
<!-- Attach screenshots or videos demonstrating UI/UX modifications -->
## 📸 Screenshots _(if applicable)_
<!-- Attach screenshots or videos for UI changes -->
---
## ⚠️ Required Pre-Submission Checklist
## ✅ Pre-Submission Checklist
### **Please Read - This Checklist is Mandatory**
> **All boxes must be checked before requesting review.** Incomplete PRs will be closed without review, no exceptions.
> **Important Notice:** We've experienced several production bugs recently due to incomplete pre-submission checks. To maintain code quality and prevent issues from reaching production, we're enforcing stricter adherence to this checklist.
>
> **All checkboxes below must be completed before requesting review.** PRs that haven't completed these requirements will be sent back for completion.
- [ ] Code follows project style guidelines and conventions
- [ ] Branch is up to date with `develop` (merge conflicts resolved)
- [ ] Automated tests added or updated to cover changes (backend **and** frontend)
- [ ] All tests pass locally (`./gradlew test` for backend, `ng test` for frontend)
- [ ] Changes manually verified in local dev environment (including related features)
- [ ] Flyway migration versioning is correct _(if schema was modified)_
- [ ] Documentation PR submitted to [booklore-docs](https://github.com/booklore-app/booklore-docs) _(if user-facing changes)_
- [ ] PR is reasonably scoped (PRs over 500+ changed lines will be closed, split into smaller PRs)
#### **Mandatory Requirements** _(please check ALL boxes)_:
### 🤖 AI-Assisted Contributions
- [ ] **Code adheres to project style guidelines and conventions**
- [ ] **Branch synchronized with latest `develop` branch** _(please resolve any merge conflicts)_
- [ ] **🚨 CRITICAL: Automated unit tests added/updated to cover changes** _(MANDATORY for ALL Spring Boot backend and Angular frontend changes - this is non-negotiable)_
- [ ] **🚨 CRITICAL: All tests pass locally** _(run `./gradlew test` for Spring Boot backend, and `ng test` for Angular frontend - NO EXCEPTIONS)_
- [ ] **🚨 CRITICAL: Manual testing completed in local development environment** _(verify your changes work AND no existing functionality is broken - test related features thoroughly)_
- [ ] **Flyway migration versioning follows correct sequence** _(if database schema was modified)_
- [ ] **Documentation PR submitted to [booklore-docs](https://github.com/booklore-app/booklore-docs)** _(required for features or enhancements that introduce user-facing or visual changes)_
> **If any part of this PR was generated or assisted by AI tools (Copilot, Claude, ChatGPT, etc.), all items below are mandatory.** AI-generated code that hasn't been thoroughly reviewed is the leading cause of reverted PRs. You are responsible for every line you submit. "The AI wrote it" is not an excuse.
#### **Why This Matters:**
Recent production incidents have been traced back to:
- **Incomplete testing coverage (especially backend)**
- Merge conflicts not resolved before merge
- Missing documentation for new features
**Backend changes without tests will not be accepted.** By completing this checklist thoroughly, you're helping maintain the quality and stability of Booklore for all users.
**Note to Reviewers:** Please verify the checklist is complete before beginning your review. If items are unchecked, kindly ask the contributor to complete them first.
- [ ] Every line has been read, understood, and can be explained by the author
- [ ] PR is scoped to a single logical change, not a dump of everything the AI suggested
- [ ] Tests validate actual behavior, not just coverage (AI-generated tests often assert nothing meaningful)
- [ ] No dead code, placeholder comments, `TODO`s, or unused scaffolding
---
### 💬 Additional Context _(optional)_
## 💬 Additional Context _(optional)_
<!-- Provide any supplementary information, implementation considerations, or discussion points for reviewers -->
<!-- Any extra information or discussion points for reviewers -->

537
CONTRIBUTING.md
View File

@@ -1,440 +1,343 @@
# 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.
Thanks for your interest in contributing to Booklore! Whether you're fixing bugs, adding features, improving documentation, or asking questions, every contribution helps.
---
## What is Booklore?
## 📚 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.
**Booklore** is a self-hostable digital library platform for managing and reading books and comics.
**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
- **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
## Table of Contents
- [Where to Start](#where-to-start)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Running Tests](#running-tests)
- [Making Changes](#making-changes)
- [Submitting a Pull Request](#submitting-a-pull-request)
- [Code Style](#code-style)
- [Reporting Bugs](#reporting-bugs)
- [Community & Support](#community--support)
- [Code of Conduct](#code-of-conduct)
- [License](#license)
---
## 📦 Project Structure
## Where to Start
```
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
```
Not sure where to begin? Look for issues labeled:
- [`good first issue`](https://github.com/booklore-app/booklore/labels/good%20first%20issue) - small, well-scoped tasks ideal for newcomers
- [`help wanted`](https://github.com/booklore-app/booklore/labels/help%20wanted) - tasks where maintainers would appreciate a hand
You can also check the [project roadmap](https://github.com/booklore-app/booklore/projects) for larger initiatives.
---
## 🚀 Getting Started
## Getting Started
### 1. Fork and Clone
### Fork and Clone
First, fork the repository to your GitHub account, then clone it locally:
First, [fork the repository](https://github.com/booklore-app/booklore/fork) on GitHub, then clone your fork locally:
```bash
# 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
### Keep Your Fork in Sync
Before starting work on a new feature or fix:
Before starting new work, pull the latest changes from upstream:
```bash
# 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
git checkout develop
git merge upstream/develop
git push origin develop
```
> **Note:** All work should be based on the `develop` branch, not `main`.
---
## 🧱 Local Development Setup
## Development Setup
Booklore offers two development approaches: an all-in-one Docker stack for quick setup, or manual installation for more control.
### Project Structure
### Option 1: Docker Development Stack (Recommended for Quick Start)
```
booklore/
├── booklore-ui/ # Angular frontend (TypeScript, PrimeNG)
├── booklore-api/ # Spring Boot backend (Java 21, Gradle)
├── dev.docker-compose.yml # Development Docker stack
├── assets/ # Shared assets (logos, icons)
└── local/ # Local development helpers
```
This option sets up everything with a single command:
### Option 1: Docker Development Stack (Recommended)
The fastest way to get a working environment. No local toolchain required.
```bash
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`
This starts:
**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)
| Service | URL / Port |
|------------|-----------------------|
| Frontend | http://localhost:4200 |
| Backend | http://localhost:8080 |
| MariaDB | localhost:3366 |
| Debug port | localhost:5005 |
All ports are configurable via environment variables (`FRONTEND_PORT`, `BACKEND_PORT`, `DB_PORT`, `REMOTE_DEBUG_PORT`) in the compose file.
**Stopping the stack:**
```bash
# To stop
docker compose -f dev.docker-compose.yml down
```
---
### Option 2: Manual Setup
### Option 2: Manual Local Development
For more control over your development environment, you can run each component separately.
For full control over each component or IDE integration (debugging, hot-reload, etc.).
#### Prerequisites
Ensure you have the following installed:
- **Java 21+** ([Download](https://adoptium.net/))
- **Node.js 18+** and **npm** ([Download](https://nodejs.org/))
- **MariaDB 10.6+** ([Download](https://mariadb.org/download/))
- **Git** ([Download](https://git-scm.com/))
| Tool | Version | Download |
|---------------|---------|----------------------------------------------|
| Java | 21+ | [Adoptium](https://adoptium.net/) |
| Node.js + npm | 18+ | [nodejs.org](https://nodejs.org/) |
| MariaDB | 10.6+ | [mariadb.org](https://mariadb.org/download/) |
| Git | latest | [git-scm.com](https://git-scm.com/) |
#### Frontend Setup
#### 1. Database
```bash
# Navigate to the frontend directory
cd booklore-ui
Start MariaDB and create the database:
# Install dependencies
npm install
# Start the development server
ng serve
# Or use npm script
npm start
```sql
CREATE DATABASE IF NOT EXISTS booklore;
CREATE USER 'booklore_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON booklore.* TO 'booklore_user'@'localhost';
FLUSH PRIVILEGES;
```
The frontend will be available at `http://localhost:4200/` with hot-reload enabled.
> **Tip:** You can also spin up MariaDB via Docker: `docker compose -f local/docker-compose-maria.yml up -d`
**Common Issues:**
- If you encounter dependency conflicts, try `npm install --legacy-peer-deps`
- Use `--force` only as a last resort
#### 2. Backend
---
#### Backend Setup
##### Step 1: Configure Application Properties
Create a development configuration file at `booklore-api/src/main/resources/application-dev.yml`:
Create a dev config at `booklore-api/src/main/resources/application-dev.yml`:
```yaml
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'
path-book: '/path/to/booklore-data/books'
path-config: '/path/to/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
username: booklore_user
password: your_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:
```bash
# 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
Replace the paths with actual directories on your system and ensure they exist with read/write permissions.
```bash
cd booklore-api
./gradlew bootRun --args='--spring.profiles.active=dev'
```
The backend API will be available at `http://localhost:8080/`
**Verify it's running:**
```bash
# Verify
curl http://localhost:8080/actuator/health
```
---
## 🧪 Testing
Always run tests before submitting a pull request to ensure your changes don't break existing functionality.
### Frontend Tests (Angular + Vitest)
Booklore uses [Vitest](https://vitest.dev/) for fast, modern frontend testing in the Angular app.
#### 3. Frontend
```bash
cd booklore-ui
# Run all frontend tests
ng test
# Run tests with coverage report
ng test --coverage
npm install
ng serve
```
- The coverage report will be generated in the `coverage/` directory.
- You can open `coverage/index.html` in your browser to view detailed coverage metrics.
- All new features and bug fixes should include relevant unit tests.
The UI will be available at http://localhost:4200 with hot-reload enabled.
### Backend Tests
> If you hit dependency issues, try `npm install --legacy-peer-deps`.
---
## Running Tests
Always run tests before submitting a pull request.
**Frontend (Vitest):**
```bash
cd booklore-ui
ng test # Run all tests
ng test --coverage # With coverage report (output: coverage/)
```
**Backend (JUnit + Gradle):**
```bash
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:**
```bash
./gradlew test
./gradlew test # Run all tests
./gradlew test --tests "com.booklore.api.service.BookServiceTest" # Specific class
./gradlew test jacocoTestReport # Coverage report
```
---
## 🛠️ Contributing Guidelines
## Making Changes
### 💡 Reporting Bugs
### Branch Naming
Found a bug? Help us fix it by providing detailed information:
Create branches from `develop` using these prefixes:
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:**
```markdown
**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:
| Prefix | Use for | Example |
|-------------|--------------------|------------------------------|
| `feat/` | New features | `feat/epub-reader-support` |
| `fix/` | Bug fixes | `fix/book-import-validation` |
| `refactor/` | Code restructuring | `refactor/auth-flow` |
| `docs/` | Documentation | `docs/update-install-guide` |
```bash
# 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
git checkout develop
git checkout -b feat/your-feature-name
```
#### Development Workflow
### Commit Messages
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](https://github.com/booklore-app/booklore-docs) with styling similar to other documentation pages
---
## 🧼 Code Style & Conventions
- **Angular**: Follow the [official style guide](https://angular.io/guide/styleguide)
- **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](https://www.conventionalcommits.org/) for clear, standardized commit messages.
### Format
We follow [Conventional Commits](https://www.conventionalcommits.org/):
```
<type>(<scope>): <subject>
[optional body]
[optional footer]
```
### Types
**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`
- `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:
### Examples
```bash
# 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
```
### Workflow
1. Create a branch from `develop`
2. Make your changes in small, logical commits
3. Run both frontend and backend tests
4. Update documentation if your changes affect usage
5. Run the linter and fix any issues
6. Push to your fork and open a PR targeting `develop`
---
## 🙏 Code of Conduct
## Submitting a Pull Request
Before opening your PR:
- [ ] All tests pass (`./gradlew test` and `ng test`)
- [ ] Code follows project conventions (see [Code Style](#code-style))
- [ ] IntelliJ linter shows no errors
- [ ] Branch is up-to-date with `develop`
- [ ] PR description explains *what* changed and *why*
- [ ] PR is linked to a related issue (if applicable)
- [ ] **PR is reasonably sized.** PRs with 1000+ changed lines will be closed without review. Break large changes into small, focused PRs.
- [ ] **For user-facing features:** submit a companion docs PR at [booklore-docs](https://github.com/booklore-app/booklore-docs)
### AI-Assisted Contributions
Contributions using AI tools (Copilot, Claude, ChatGPT, etc.) are welcome, but the quality bar is the same as human-written code. **If you ship it, you own it.**
- **Review every line.** You must be able to explain any part of your change during review.
- **Keep PRs focused.** One feature, one fix, or one refactor per PR.
- **Scrutinize AI-generated tests.** They often pass trivially without asserting anything meaningful.
- **Clean up.** Remove dead code, placeholder comments, empty catch blocks, and unnecessary boilerplate.
---
## Code Style
| Area | Convention |
|------------|--------------------------------------------------------------------|
| Angular | Follow the [official style guide](https://angular.dev/style-guide) |
| Java | Modern Java 21 features, clean structure |
| Formatting | Use IntelliJ IDEA's built-in linter |
| UI | SCSS with PrimeNG components |
---
## Reporting Bugs
1. **Search [existing issues](https://github.com/booklore-app/booklore/issues)** to avoid duplicates.
2. **Open a new issue** with the `bug` label including:
- Clear, descriptive title (e.g., "Book import fails with PDF files over 100MB")
- Steps to reproduce
- Expected vs. actual behavior
- Screenshots or error logs (if applicable)
- Environment details (OS, browser, Booklore version)
**Example:**
```
Title: Book metadata not updating after manual edit
Steps to Reproduce:
1. Navigate to any book detail page
2. Click "Edit Metadata"
3. Change the title and click "Save"
4. Refresh the page
Expected: Title should persist after refresh
Actual: Title reverts to original value
Environment: Chrome 120, macOS 14.2, Booklore 1.2.0
```
---
## Community & Support
- **Discord:** [Join the server](https://discord.gg/Ee5hd458Uz) for questions and discussion
- **GitHub Issues:** [Report bugs or request features](https://github.com/booklore-app/booklore/issues)
---
## 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
**Do:**
- 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
**Don't:**
- Harass, troll, or discriminate
- Make personal attacks or insults
- Publish others' private information
**Enforcement:**
Instances of unacceptable behavior may result in temporary or permanent ban from the project.
---
## 💬 Community & Support
## License
**Need help or want to discuss ideas?**
- 💬 **Discord**: [Join our server](https://discord.gg/Ee5hd458Uz)
- 🐛 **Issues**: [GitHub Issues](https://github.com/booklore-app/booklore/issues)
Booklore is licensed under the [AGPL-3.0 License](./LICENSE). By contributing, you agree that your contributions will be licensed under the same terms.
---
## 📄 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`](./LICENSE) file for full details.
---
## 🎯 What to Work On?
Not sure where to start? Check out:
- Issues labeled [`good first issue`](https://github.com/booklore-app/booklore/labels/good%20first%20issue)
- Issues labeled [`help wanted`](https://github.com/booklore-app/booklore/labels/help%20wanted)
- Our [project roadmap](https://github.com/booklore-app/booklore/projects)
---
## 🎉 Thank You!
Every contribution, no matter how small, makes Booklore better. Thank you for being part of our community!
**Happy Contributing! 📚✨**
Thank you for being part of the Booklore community!