Linus-Enjoyer/Freedom-Loader
1
1
Fork 0
mirror of https://github.com/MasterAcnolo/Freedom-Loader.git synced 2026-09-27 20:11:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

add: DEVELOPMENT.md file and refactor contributing and README

Browse Source
This commit is contained in:
MasterAcnolo
2026-08-16 10:36:36 +02:00
parent 62c109939a
commit 4573917541
3 changed files with 411 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
CONTRIBUTING.md
View File

@@ -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
2. Create a feature branch: `git checkout -b feature/your-feature-name`
3. Make your changes
4. Test thoroughly on Windows 10/11 and Linux (If possible)
5. Commit with clear messages: `git commit -m "Add feature X"`
6. Push to your fork: `git push origin feature/your-feature-name`
7. Open a Pull Request using the appropriate template
1. Fork the repository.
2. Check out our [**Developer Guide (DEVELOPMENT.md)**](./DEVELOPMENT.md) to set up your environment.
3. Create a feature branch following our branching conventions.
4. Make your changes and test thoroughly on Windows and/or Linux.
5. 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
- Node.js 16.x or higher
- npm or yarn
- Git
- Windows 10/11 (for testing)
- Any Linux Distribution (for testing)
Want to write some code? Awesome!
### Setup
```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
```
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.
---
@@ -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
---

388
DEVELOPMENT.md Normal file
View File

@@ -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! 🎉

70
README.md
View File

@@ -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
- 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
```
If you are interested by running a local non compiled version of Freedom Loader or just interested by contributing, see [DEVELOPMENT](./DEVELOPMENT.md)
### Additional Dependencies
@@ -446,40 +425,19 @@ You must download the required binaries and place them in the `resources` folder
#### Required binaries
- **Deno**
- 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.
See [BINARIES.md](./BINARIES.md) for how to setup the binaries.
### Development Guidelines
- Follow existing code style and conventions
- Write clear commit messages
- Test thoroughly before submitting changes
- Update documentation when adding features
- Maintain compatibility with Windows 10+ and Linux
- Write clear, imperative commit messages (e.g., "Add playlist indexing" not "Added")
- Test thoroughly on both Windows and Linux before submitting changes
- Update documentation (README, DEVELOPMENT.md) when adding features
- 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