mirror/booklore
1
0
Fork 0
mirror of https://github.com/booklore-app/booklore.git synced 2025-12-23 14:20:48 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update github templates (#1840)

Browse Source
This commit is contained in:
Aditya Chandel
2025-12-12 16:12:44 -07:00
committed by GitHub
parent 475f605f26
commit eff090d825
4 changed files with 358 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -1,21 +1,6 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
# 🐛 Bug Report
---
# 🐛 Bug Report for Booklore
Thank you for taking the time to report this bug. Your feedback helps make Booklore better for everyone!
Let's squash this bug together! 🔨
---
## 📝 What happened?
## 📝 Description
<!-- Describe what went wrong -->
@@ -28,11 +13,12 @@ ## 🔄 Steps to Reproduce
**Result:** <!-- What happened after these steps? -->
## ✅ Expected Behavior
<!-- Describe what should have happened instead -->
## 📸 Screenshots / Error Messages
## 📸 Screenshots / Error Messages _(Optional)_
<!-- Share any screenshots or error messages here (just drag & drop) -->
@@ -44,9 +30,10 @@ ## 💻 Environment
- **Installation:** (e.g., Docker, Unraid, Manual)
- **Storage Type:** (e.g., Local HDD/SSD, Synology NAS, SMB Share, NFS Mount, S3 Bucket)
## 📌 Additional Context
<!-- Add any other relevant information: recent changes, specific books, configuration details, etc. -->
## ✨ Possible Solution _(Optional)_
## 💡 Possible Solution _(Optional)_
<!-- Share any ideas on how to fix this issue -->
## 📌 Additional Context _(Optional)_
<!-- Add any other relevant information: recent changes, specific books, configuration details, etc. -->

17
.github/ISSUE_TEMPLATE/feature_request.md vendored
View File

@@ -1,17 +1,4 @@
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
---
# ✨ Feature Request for Booklore
Thank you for contributing to Booklore's development. Your suggestions help shape the future of this project.
---
# ✨ Feature Request
## 📝 Description
<!-- Describe the problem you're facing and the solution you're proposing -->
@@ -36,5 +23,5 @@ ## 🎨 Technical Details _(Optional)_
<!-- Share implementation ideas, alternative solutions, or related features -->
## 📌 Additional Context
## 📌 Additional Context _(Optional)_
<!-- Any other information, research, or context that would be helpful -->

39
.github/PULL_REQUEST_TEMPLATE/pull_request_template.md vendored Normal file
View File

@@ -0,0 +1,39 @@
# 🚀 Pull Request
## 📝 Description
<!-- Briefly describe the purpose of this pull request. What problem does it solve? -->
<!-- Link to the related issue, if any. Ex: "Fixes #123" or "Closes #456" -->
## 🛠️ What's Changed?
<!-- Provide a clear and concise summary of the changes you've made. -->
<!-- Bullet points are great for listing multiple changes. -->
-
## 🧪 How Was This Tested?
<!-- Describe the steps you took to verify your changes work as expected. -->
<!-- This helps reviewers understand your testing process. -->
- [ ] Manual testing on my local machine
- [ ] Added new unit/integration tests
- [ ] All existing tests pass
## 📸 Screenshots / Videos _(Optional)_
<!-- If your changes affect the UI, please add screenshots or a short video. -->
<!-- This makes it much easier to review visual changes. -->
## ✅ Checklist
<!-- Go through this checklist before submitting your PR. -->
- [ ] I have read the **CONTRIBUTING** document.
- [ ] My code follows the project's coding standards.
- [ ] I have added/updated tests to cover my changes.
- [ ] I have updated the documentation if necessary.
- [ ] I have run `./gradlew test` successfully (for backend changes).
- [ ] My branch is up-to-date with the `main` branch.
- [ ] **For big features:** I have created a documentation PR at [booklore-docs](https://github.com/booklore-app/booklore-docs) with styling similar to other documentation pages.
## 📌 Additional Context _(Optional)_
<!-- Any other information that might be helpful for reviewers? -->

396
CONTRIBUTING.md
View File

@@ -1,16 +1,17 @@
# 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!
🎉 **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.
---
## 📚 Overview
## 📚 What is Booklore?
**Booklore** is a self-hostable platform designed to manage and read books and comics. It includes:
**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.
- **Frontend**: Angular 20, TypeScript, PrimeNG 19, Tailwind CSS
**Tech Stack:**
- **Frontend**: Angular 20, TypeScript, PrimeNG 19
- **Backend**: Java 21, Spring Boot 3.5
- **Authentication**: Local JWT + optional OIDC (e.g. Authentik)
- **Authentication**: Local JWT + optional OIDC (e.g., Authentik)
- **Database**: MariaDB
- **Deployment**: Docker-compatible, reverse proxy-ready
@@ -20,116 +21,202 @@ ## 📦 Project Structure
```
booklore/
├── booklore-ui/ # Angular frontend
├── booklore-api/ # Spring Boot backend
├── assets/ # Shared assets
├── 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 the repository** on GitHub
2. **Clone your fork** locally:
### 1. Fork and Clone
First, fork the repository to your GitHub account, then clone it locally:
```bash
git clone https://github.com/adityachandelgit/BookLore.git
# 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:
```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
```
---
## 🧱 Local Development Setup
Booklore has a simple all-in-one Docker development stack, or you can install & run everything manually.
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)
### 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:
This option sets up everything with a single command:
```bash
cd booklore-ui
npm install
ng serve
docker compose -f dev.docker-compose.yml up
```
The dev server runs at `http://localhost:4200/`.
**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`
> ⚠️ Use `--force` with `npm install` only as a last resort for dependency conflicts.
**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:**
```bash
docker compose -f dev.docker-compose.yml down
```
---
#### 3. Backend Setup
### Option 2: Manual Local Development
##### a. Configure `application-dev.yml`
For more control over your development environment, you can run each component separately.
Create or edit `booklore-api/src/main/resources/application-dev.yml`:
#### 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/))
#### Frontend Setup
```bash
# 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`:
```yaml
app:
path-book: '/path/to/booklore/books' # Directory for book/comic files
path-config: '/path/to/booklore/config' # Directory for thumbnails, metadata, etc.
# 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:3333/booklore?createDatabaseIfNotExist=true
url: jdbc:mariadb://localhost:3306/booklore?createDatabaseIfNotExist=true
username: root
password: Password123
password: your_secure_password
```
> 🔧 Replace `/path/to/...` with actual local paths
**Important:**
- Replace `/Users/yourname/...` with actual paths on your system
- Create these directories if they don't exist
- Ensure proper read/write permissions
##### b. Run the Backend
**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
```bash
cd booklore-api
./gradlew bootRun
./gradlew bootRun --args='--spring.profiles.active=dev'
```
The backend API will be available at `http://localhost:8080/`
**Verify it's running:**
```bash
curl http://localhost:8080/actuator/health
```
---
## 🧪 Testing
### Frontend
Always run tests before submitting a pull request to ensure your changes don't break existing functionality.
Run unit tests using:
```bash
cd booklore-ui
ng test
```
### Backend
Run backend tests using:
### Backend Tests
```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
```
@@ -137,74 +224,199 @@ ### Backend
## 🛠️ Contributing Guidelines
### 💡 Bug Reports
### 💡 Reporting Bugs
- Check [existing issues](https://github.com/adityachandelgit/BookLore/issues)
- Include reproduction steps, expected vs. actual behavior, and logs if possible
Found a bug? Help us fix it by providing detailed information:
### 🌟 Feature Requests
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.)
- Clearly explain the use case and benefit
- Label the issue with `feature`
**Example Bug Report:**
```markdown
**Title:** Book metadata not updating after manual edit
### 🔃 Code Contributions
**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.
- Create a feature branch:
**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
```bash
git checkout -b feat/my-feature
**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
```
- For bug fixes:
---
### 🔃 Submitting Code Changes
#### Branch Naming Convention
Create descriptive branches that clearly indicate the purpose of your changes:
```bash
git checkout -b fix/my-fix
# 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
```
- 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
#### 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](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 17+), clean structure
- **Format**: Use linters and Prettier where applicable
- **UI**: Use Tailwind CSS and PrimeNG components consistently
- **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
Follow [Conventional Commits](https://www.conventionalcommits.org/):
We follow [Conventional Commits](https://www.conventionalcommits.org/) for clear, standardized commit messages.
Examples:
### Format
- `feat: add column visibility setting to book table`
- `fix: correct metadata locking behavior`
- `docs: improve contributing instructions`
```
<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
```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
```
---
## 🙏 Code of Conduct
Please be respectful, inclusive, and collaborative. Harassment, abuse, or discrimination of any kind will not be tolerated.
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
- Discord server: https://discord.gg/Ee5hd458Uz
**Need help or want to discuss ideas?**
- 💬 **Discord**: [Join our server](https://discord.gg/Ee5hd458Uz)
- 🐛 **Issues**: [GitHub Issues](https://github.com/adityachandelgit/BookLore/issues)
---
## 📄 License
Booklore is open-source and licensed under the GPL-3.0 License. See [`LICENSE`](./LICENSE) for details.
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.
---
Happy contributing!
## 🎯 What to Work On?
Not sure where to start? Check out:
- Issues labeled [`good first issue`](https://github.com/adityachandelgit/BookLore/labels/good%20first%20issue)
- Issues labeled [`help wanted`](https://github.com/adityachandelgit/BookLore/labels/help%20wanted)
- Our [project roadmap](https://github.com/adityachandelgit/BookLore/projects)
---
## 🎉 Thank You!
Every contribution, no matter how small, makes Booklore better. Thank you for being part of our community!
**Happy Contributing! 📚✨**