mirror of
https://github.com/booklore-app/booklore.git
synced 2025-12-23 22:28:11 -05:00
cc38079c40
* Enable java remote debug on dev stack * Enable java remote debug on dev stack * Update docs with info on docker development stack * Update dev docs
211 lines
4.3 KiB
Markdown
211 lines
4.3 KiB
Markdown
# Contributing to Booklore
|
|
|
|
🎉 Thanks for your interest in contributing to **Booklore**, a modern, self-hostable digital library system for books and comics. Whether you're fixing bugs, adding features, improving documentation, or asking questions - your contribution matters!
|
|
|
|
---
|
|
|
|
## 📚 Overview
|
|
|
|
**Booklore** is a self-hostable platform designed to manage and read books and comics. It includes:
|
|
|
|
- **Frontend**: Angular 20, TypeScript, PrimeNG 19, Tailwind CSS
|
|
- **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
|
|
├── booklore-api/ # Spring Boot backend
|
|
├── assets/ # Shared assets
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Getting Started
|
|
|
|
1. **Fork the repository** on GitHub
|
|
2. **Clone your fork** locally:
|
|
|
|
```bash
|
|
git clone https://github.com/adityachandelgit/BookLore.git
|
|
cd booklore
|
|
```
|
|
|
|
---
|
|
|
|
## 🧱 Local Development Setup
|
|
|
|
Booklore has a simple all-in-one Docker development stack, or you can install & run everything manually.
|
|
|
|
|
|
### Development using Docker stack
|
|
|
|
Run `docker compose -f dev.docker-compose.yml up`
|
|
|
|
- Dev web server is accessible at `http://localhost:4200/`
|
|
- Dev database is accessible at `http://localhost:3366/`
|
|
- Remote java debugging is accessible at `http://localhost:5005/`
|
|
|
|
All ports are configurable using environment variables - see dev.docker-compose.yml
|
|
|
|
---
|
|
|
|
### Development on local machine
|
|
|
|
#### 1. Prerequisites
|
|
|
|
- **Java 21+**
|
|
- **Node.js 18+**
|
|
- **MariaDB**
|
|
- **Docker and Docker Compose**
|
|
|
|
---
|
|
|
|
#### 2. Frontend Setup
|
|
|
|
To set up the Angular frontend:
|
|
|
|
```bash
|
|
cd booklore-ui
|
|
npm install
|
|
ng serve
|
|
```
|
|
|
|
The dev server runs at `http://localhost:4200/`.
|
|
|
|
> ⚠️ Use `--force` with `npm install` only as a last resort for dependency conflicts.
|
|
|
|
---
|
|
|
|
#### 3. Backend Setup
|
|
|
|
##### a. Configure `application-dev.yml`
|
|
|
|
Create or edit `booklore-api/src/main/resources/application-dev.yml`:
|
|
|
|
```yaml
|
|
app:
|
|
path-book: '/path/to/booklore/books' # Directory for book/comic files
|
|
path-config: '/path/to/booklore/config' # Directory for thumbnails, metadata, etc.
|
|
|
|
spring:
|
|
datasource:
|
|
driver-class-name: org.mariadb.jdbc.Driver
|
|
url: jdbc:mariadb://localhost:3333/booklore?createDatabaseIfNotExist=true
|
|
username: root
|
|
password: Password123
|
|
```
|
|
|
|
> 🔧 Replace `/path/to/...` with actual local paths
|
|
|
|
##### b. Run the Backend
|
|
|
|
```bash
|
|
cd booklore-api
|
|
./gradlew bootRun
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Testing
|
|
|
|
### Frontend
|
|
|
|
Run unit tests using:
|
|
|
|
```bash
|
|
cd booklore-ui
|
|
ng test
|
|
```
|
|
|
|
### Backend
|
|
|
|
Run backend tests using:
|
|
|
|
```bash
|
|
cd booklore-api
|
|
./gradlew test
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Contributing Guidelines
|
|
|
|
### 💡 Bug Reports
|
|
|
|
- Check [existing issues](https://github.com/adityachandelgit/BookLore/issues)
|
|
- Include reproduction steps, expected vs. actual behavior, and logs if possible
|
|
|
|
### 🌟 Feature Requests
|
|
|
|
- Clearly explain the use case and benefit
|
|
- Label the issue with `feature`
|
|
|
|
### 🔃 Code Contributions
|
|
|
|
- Create a feature branch:
|
|
|
|
```bash
|
|
git checkout -b feat/my-feature
|
|
```
|
|
|
|
- For bug fixes:
|
|
|
|
```bash
|
|
git checkout -b fix/my-fix
|
|
```
|
|
|
|
- Follow code conventions, keep PRs focused and scoped
|
|
- Link the relevant issue in your PR
|
|
- Test your changes
|
|
- Target the `develop` branch when opening PRs
|
|
|
|
---
|
|
|
|
## 🧼 Code Style & Conventions
|
|
|
|
- **Angular**: Follow the [official style guide](https://angular.io/guide/styleguide)
|
|
- **Java**: Use modern features (Java 17+), clean structure
|
|
- **Format**: Use linters and Prettier where applicable
|
|
- **UI**: Use Tailwind CSS and PrimeNG components consistently
|
|
|
|
---
|
|
|
|
## 📝 Commit Message Format
|
|
|
|
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
|
|
Examples:
|
|
|
|
- `feat: add column visibility setting to book table`
|
|
- `fix: correct metadata locking behavior`
|
|
- `docs: improve contributing instructions`
|
|
|
|
---
|
|
|
|
## 🙏 Code of Conduct
|
|
|
|
Please be respectful, inclusive, and collaborative. Harassment, abuse, or discrimination of any kind will not be tolerated.
|
|
|
|
---
|
|
|
|
## 💬 Community & Support
|
|
|
|
- Discord server: https://discord.gg/Ee5hd458Uz
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
Booklore is open-source and licensed under the GPL-3.0 License. See [`LICENSE`](./LICENSE) for details.
|
|
|
|
---
|
|
|
|
Happy contributing!
|