From 4573917541d0cb788e09d7b5c813cd9bbc2b9992 Mon Sep 17 00:00:00 2001 From: MasterAcnolo <68693319+MasterAcnolo@users.noreply.github.com> Date: Sun, 16 Aug 2026 10:36:36 +0200 Subject: [PATCH] add: DEVELOPMENT.md file and refactor contributing and README --- CONTRIBUTING.md | 39 ++--- DEVELOPMENT.md | 388 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 70 ++------- 3 files changed, 411 insertions(+), 86 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4311adf..a897588 100644 --- a/CONTRIBUTING.md +++ b/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 -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 --- diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..b518e70 --- /dev/null +++ b/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! 🎉 \ No newline at end of file diff --git a/README.md b/README.md index 9a03b9e..5fcc246 100644 --- a/README.md +++ b/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) + - [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 + ### 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