add: DEVELOPMENT.md file and refactor contributing and README

CONTRIBUTING.md

@@ -23,7 +23,7 @@ Found a bug or unexpected behavior? Open an [**issue**](https://github.com/Maste
 - Clear description of the bug
 - Steps to reproduce
 - App version and environment (Windows version, Firefox version if relevant)
-- Logs from: `C:\Users\[USERNAME]\AppData\Local\FreedomLoader\logs\LOGS-YYYY-MM-DD.log`
+- Logs from: `C:\Users\[USERNAME]\AppData\Local\FreedomLoader\logs\LOGS-YYYY-MM-DD.log` (Windows) or `~/.local/share/FreedomLoader/logs/` (Linux)
 - Screenshots if applicable
 
 ### 2. Request a Feature
@@ -43,13 +43,11 @@ Have an idea to improve Freedom Loader? Open a [**Feature Request**](https://git
 - Follow the project's code style and conventions
 
 **Process:**
-1. Fork the repository
+1. Fork the repository.
-2. Create a feature branch: `git checkout -b feature/your-feature-name`
+2. Check out our [**Developer Guide (DEVELOPMENT.md)**](./DEVELOPMENT.md) to set up your environment.
-3. Make your changes
+3. Create a feature branch following our branching conventions.
-4. Test thoroughly on Windows 10/11 and Linux (If possible)
+4. Make your changes and test thoroughly on Windows and/or Linux.
-5. Commit with clear messages: `git commit -m "Add feature X"`
+5. Open a Pull Request using the appropriate template.
-6. Push to your fork: `git push origin feature/your-feature-name`
-7. Open a Pull Request using the appropriate template
 
 **Code Guidelines:**
 - Use camelCase for variables and functions
@@ -72,28 +70,9 @@ Small contributions matter—don't hesitate to submit documentation PRs.
 
 ## Development Setup
 
-### Prerequisites
+Want to write some code? Awesome! 
-- Node.js 16.x or higher
-- npm or yarn
-- Git
-- Windows 10/11 (for testing)
-- Any Linux Distribution (for testing)
 
-### Setup
+Please read our [**Developer Guide (DEVELOPMENT.md)**](./DEVELOPMENT.md) for instructions on how to set up your local environment, our project architecture, and our Git branching rules.
-```bash
-# Clone your fork
-git clone https://github.com/MasterAcnolo/Freedom-Loader.git
-cd Freedom-Loader
-
-# Install dependencies
-npm install
-
-# Run in development mode
-npm start
-
-# Build for production
-npm run build
-```
 
 ---
 
@@ -103,7 +82,7 @@ Before submitting a PR, verify:
 - [ ] Download functionality works (video/audio)
 - [ ] No errors in application logs
 - [ ] Any features wasn't break during the development
-- [ ] Tested on Windows 10 and/or Windows 11 and/or any Linux Distribution
+- [ ] Tested on Windows 10/11 and/or any Linux Distribution
 
 ---
 

DEVELOPMENT.md

@@ -0,0 +1,388 @@
+# Freedom Loader - Development Guide
+
+Welcome to the Developer Guide! This document explains how to set up your local environment, project architecture, Git workflow, and the release process.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed on your machine:
+
+- **Node.js** (v22 or higher recommended)
+- **npm** (comes with Node.js)
+- **Git**
+- **yt-dlp binaries**: Freedom Loader requires native binaries to function. Read [BINARIES.md](./BINARIES.md) for download instructions and placement in `resources/binaries/`.
+
+## Setup Instructions
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/MasterAcnolo/Freedom-Loader.git
+cd Freedom-Loader
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+### 3. Install the Binaries
+
+Follow the instructions in `BINARIES.md` to place `yt-dlp`, `ffmpeg`, `ffprobe`, and `deno` in the correct `resources/binaries/` folder for your OS.
+
+### 4. Run in Development Mode
+
+```bash
+npm start
+```
+
+**Note**: Development mode automatically enables detailed colored logs and the DevTron extension for debugging.
+
+---
+
+## Available Scripts
+
+### Development
+
+- `npm start` — Start the app in development mode (no warnings)
+- `npm run start:warn` — Start with deprecation warnings visible
+- `npm run start:debug` — Start with full debug logging (Wayland, Electron logging, stack dumps)
+- `npm run dev` — Start with auto-reload on file changes (watches server/, app/, main.js, config.js)
+- `npm run dev:warn` — Dev mode with warnings
+- `npm run dev:debug` — Dev mode with full debug output and auto-reload
+
+### Building
+
+- `npm run build:linux` — Build Linux packages (AppImage, deb, snap)
+- `npm run build:win` — Build Windows installer (.exe)
+- `npm run build:rpm` — Build RPM and SRPM for COPR (Fedora)
+- `npm run build:all` — Build both Windows and Linux (not recommended — see below)
+
+### Testing
+
+- `npm test` — Run all tests (unit + integration)
+- `npm run test:unit` — Run unit tests only
+
+### Release Pipeline
+
+- `npm run release` — Build all packages and create a draft GitHub release (no store publishing)
+- `npm run release:publish` — Build all packages and publish to Snap Store + COPR
+- `npm run release:dry-run` — Simulate the full release pipeline without publishing anything
+
+### Maintenance
+
+- `npm update` — Update npm dependencies
+
+---
+
+## Project Architecture
+
+Freedom Loader is built with **Electron** (frontend) and **Node.js + Express** (backend), using a modular structure:
+
+---
+
+## Git & Branching Workflow
+
+I use **Trunk-Based Development** (GitHub Flow):
+
+### Core Principles
+
+- **`main` is always deployable**: The `main` branch contains the latest stable code and must never be broken.
+- **No long-lived branches**: I no longer maintain version branches like `v1.6` or `v1.7`.
+- **Pull Requests for review**: All code changes go through PR review before merging to `main`.
+
+### How to Contribute
+
+#### 1. Create a feature branch
+
+```bash
+git checkout -b feat/add-new-button
+# or for fixes:
+git checkout -b fix/ui-bug
+```
+
+**Branch naming convention**:
+- `feat/` — New features
+- `fix/` — Bug fixes
+- `refactor/` — Code cleanup (no behavior change)
+- `docs/` — Documentation updates
+- `chore/` — Dependency updates, build config, etc.
+
+#### 2. Make commits
+
+```bash
+# Make changes
+git add .
+git commit -m "Brief, imperative description of the change"
+```
+
+**Commit message tips**:
+- Use imperative mood: "Add theme caching" not "Added theme caching"
+- Keep commits logical and focused (one feature per commit if possible)
+- Link to issues if relevant: "Fix crash on download (fixes #42)"
+
+#### 3. Push and open a PR
+
+```bash
+git push origin feat/add-new-button
+```
+
+Then open a PR on GitHub against `main`.
+
+#### 4. Review and merge
+
+- Address feedback in new commits (don't rebase — easier to review)
+- Once approved, merge via GitHub (use "Squash and merge" for clean history if many small commits and you find it relevant)
+
+---
+
+## Release Process
+
+**Note**: Only project maintainers release to production. This section documents the process for transparency and for future maintainers.
+
+Releases are fully automated via the `release.sh` script. The process handles building, packaging, and publishing to **all distribution channels**:
+- **GitHub Releases** (Windows .exe, Linux packages)
+- **Fedora COPR** (automatic RPM builds for Fedora 43+)
+- **Snap Store** (universal Linux)
+
+### Before You Release
+
+1. **Ensure `main` is green**: All tests pass, features are stable.
+2. **Update `package.json` version**:
+
+```json
+   "version": "1.6.1"
+```
+3. **Commit the version bump**: `git add package.json && git commit -m "chore: v1.6.1"`
+4. **Push to `main`**: `git push origin main`
+
+### Step 1: Local Build & Draft Release
+
+```bash
+npm run release
+```
+
+This:
+1. Builds Linux packages (AppImage, deb, snap)
+2. Builds RPM and SRPM for COPR
+3. Builds Windows installer
+4. Creates a draft GitHub release
+
+### Step 2: Edit & Publish on GitHub
+
+1. Go to https://github.com/MasterAcnolo/Freedom-Loader/releases
+2. Edit the draft release — fill in changelog
+3. Click **"Publish"** to make it live
+
+### Step 3: Publish to Distribution Channels
+
+```bash
+npm run release:publish
+```
+
+This automatically:
+- **Uploads to Snap Store**: Makes the app available via `snap install freedom-loader`
+- **Submits to Fedora COPR**: Builds and publishes RPMs for Fedora 43+ (users can `dnf install freedom-loader` from the COPR repo)
+
+Both happen in parallel — users across all platforms get the release simultaneously.
+
+---
+
+## Linux Development Considerations
+
+### Cross-Distribution Compatibility
+
+Freedom Loader targets **Debian-based** (Ubuntu, Debian) and **Fedora-based** (Fedora, RHEL, openSUSE) distributions. When developing features, keep this in mind:
+
+#### What to test
+
+- **Feature works on Fedora 44+** (primary Linux development environment)
+- **Feature works on Ubuntu/Debian** (via deb package or AppImage)
+- **Feature doesn't break Snap confinement** (Snap has restricted filesystem/IPC access)
+- **Feature gracefully degrades on missing system dependencies**
+
+#### Desktop Environment (DE) Compatibility
+
+Test on at least **GNOME** and **KDE** (the most common DEs). Common pain points:
+
+- **Themes**: May render differently on KDE vs GNOME — test both if possible
+- **File dialogs**: Some DEs use native file pickers, others fall back to Electron's
+- **Notifications**: System notification APIs vary (D-Bus, libnotify)
+- **Tray icons**: May not work identically across DEs
+
+#### How to check locally
+
+```bash
+# Test on Fedora (if available)
+npm run build:linux
+sudo dnf install dist/freedom-loader-*.x86_64.rpm
+freedom-loader
+
+# Test AppImage (works on any distro)
+chmod +x dist/Freedom\ Loader-*.AppImage
+./dist/Freedom\ Loader-*.AppImage
+```
+
+### CI/CD Gap
+
+**Currently**: No automated testing across distros or DEs. Releases rely on manual testing before publish.
+
+**Future improvement**: Automated tests via GitHub Actions (Ubuntu) + local testing on Fedora would catch cross-distro issues early. This is planned but not yet implemented.
+
+For now, if you fix a Linux-specific bug or add a DE-dependent feature, **please mention it in your PR description** so reviewers can test extra carefully.
+
+---
+
+## Testing
+
+### Unit Tests
+
+Test individual functions in isolation (no Electron required).
+
+```bash
+npm run test:unit
+```
+
+Covered:
+
+(Tests will come soon)
+
+### End-to-End Tests (Playwright)
+
+Test the actual Electron app launching and basic UI interactions.
+
+```bash
+npm run test
+```
+
+Covered:
+
+(Tests will come soon)
+
+
+### Running All Tests
+
+```bash
+npm test
+```
+
+Or include tests before release:
+
+```bash
+npm test && npm run release
+```
+
+---
+
+## Common Tasks
+
+### Add a new feature
+
+1. Create a feature branch: `git checkout -b feat/my-feature`
+2. Make changes, commit: `git add . && git commit -m "feat: my feature"`
+3. Push: `git push origin feat/my-feature`
+4. Open a PR on GitHub
+5. Once approved, merge to `main`
+6. (Later) Cut a release when ready: `npm run release`
+
+### Fix a bug
+
+Same as above, but use `fix/bug-name` branch and `git commit -m "fix: description"`.
+
+### Test the app before releasing
+
+```bash
+npm run dev        # Auto-reload on file changes
+# Make changes, test in the UI
+npm test           # Run all tests
+npm run release:dry-run   # Simulate release (builds but doesn't publish)
+```
+
+### Update dependencies
+
+```bash
+npm update
+git add package.json package-lock.json
+git commit -m "chore: update dependencies"
+git push origin main
+```
+
+### Rebuild only Linux (after quick fixes)
+
+```bash
+npm run build:linux
+# Or just the RPM:
+npm run build:rpm
+```
+
+### Publish to stores manually
+
+If `npm run release:publish` fails partway:
+
+```bash
+# Just Snap:
+snapcraft upload dist/freedom-loader_*.snap --release=stable
+
+# Just COPR:
+copr-cli build freedom-loader srpm-out/*.src.rpm
+```
+
+---
+
+## Troubleshooting
+
+### App won't start in dev mode
+
+```bash
+npm run start:debug
+```
+
+Check the debug output for errors. Most common:
+- Missing binaries in `resources/binaries/`
+- Port 8787 already in use
+- A dead instance is still running — open Task Manager and kill the "Freedom Loader" process
+
+### (Linux) Binaries in the right place but app still won't launch
+
+You probably forgot to make them executable:
+
+```bash
+chmod +x resources/binaries/linux/*
+```
+
+The app will fail silently if binaries lack execute permissions.
+
+### Build fails with "permission denied"
+
+Make sure you have write access to `dist/` and `srpm-out/`:
+
+```bash
+chmod -R u+w dist srpm-out
+npm run build:linux
+```
+
+### Tests fail
+
+Check for:
+- Missing test files in `tests/unit/`
+- Node modules out of sync: `rm -rf node_modules && npm install`
+
+### GitHub release publish fails
+
+Verify `gh` CLI is installed and authenticated:
+
+```bash
+gh auth login
+gh release list
+```
+
+---
+
+## Questions?
+
+For more info:
+- **Electron docs**: https://www.electronjs.org/docs
+- **electron-builder**: https://www.electron.build/
+- **This repo**: https://github.com/MasterAcnolo/Freedom-Loader
+
+Happy coding! 🎉

README.md

@@ -35,7 +35,7 @@ The primary goal is to make media downloading accessible to users who want offli
 - [Usage](#usage)
 - [Preview](#preview)
 - [Configuration](#configuration)
-- [Project Structure](#project-structure)
+<!-- - [Project Structure](#project-structure) -->
 - [Theme Workshop](#Theme-Workshop)
 - [Technology Stack](#technology-stack)
 - [Development](#development)
@@ -285,7 +285,7 @@ Freedom Loader can be configured either through the settings panel in the UI or
 > [!NOTE]
 > Some configuration changes may require an application restart to take effect.
 
-## Project Structure
+<!-- ## Project Structure
 
 ```
 Freedom-Loader/
@@ -366,7 +366,7 @@ Freedom-Loader/
 ├── package.json             # Project metadata and dependencies
 ├── preload.js               # Electron preload script (IPC bridge)
 └── README.md                # This file
-```
+``` -->
 
 ### Architecture Overview
 
@@ -414,28 +414,7 @@ Freedom Loader includes a web-based theme creator available at [Freedom Loader W
 
 ## Development
 
-### Prerequisites
+If you are interested by running a local non compiled version of Freedom Loader or just interested by contributing, see [DEVELOPMENT](./DEVELOPMENT.md)
-
-- Node.js 16.x or higher
-- npm or yarn
-- Git
-
-### Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/MasterAcnolo/Freedom-Loader.git
-cd Freedom-Loader
-
-# Install dependencies
-npm install
-
-# Run in development mode
-npm start
-
-# Build for production
-npm run build
-```
 
 ### Additional Dependencies
 
@@ -446,40 +425,19 @@ You must download the required binaries and place them in the `resources` folder
 
 #### Required binaries
 
-- **Deno**
+See [BINARIES.md](./BINARIES.md) for how to setup the binaries.
-  - Download from: https://sourceforge.net/projects/deno.mirror/files/latest/download
-  - Rename to: `deno.exe`
-
-- **FFmpeg**
-  - Download from: https://www.ffmpeg.org/download.html
-  - Required files:
-    - `ffmpeg.exe`
-    - `ffprobe.exe`
-
-- **yt-dlp**
-  - Already bundled with the project  
-  - No manual installation required
-
-Final folder structure:
-
-```
-resources/
-├── deno.exe
-├── ffmpeg.exe
-├── ffprobe.exe
-└── yt-dlp.exe
-```
-
-> These binaries are required for the application to start correctly.  
-> If any of them are missing, an error message will be displayed at application startup.
 
 ### Development Guidelines
 
 - Follow existing code style and conventions
-- Write clear commit messages
+- Write clear, imperative commit messages (e.g., "Add playlist indexing" not "Added")
-- Test thoroughly before submitting changes
+- Test thoroughly on both Windows and Linux before submitting changes
-- Update documentation when adding features
+- Update documentation (README, DEVELOPMENT.md) when adding features
-- Maintain compatibility with Windows 10+ and Linux
+- Maintain compatibility with:
+  - Windows 10+
+  - Fedora 43+ / Debian 11+ / Ubuntu 20.04+
+  - GNOME and KDE desktop environments (when possible)
+- Consider Linux distribution differences early (see [DEVELOPMENT.md](./DEVELOPMENT.md#linux-development-considerations))
 
 ## Roadmap
 
@@ -521,7 +479,7 @@ Open a feature request issue with:
 5. Update documentation as needed
 6. Submit a pull request with a detailed description
 
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md), [DEVELOPMENT.md](./DEVELOPMENT.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
 
 ## Support