From d7169a91194f26319e26b24caa40a8dfb001cee9 Mon Sep 17 00:00:00 2001 From: Brendan Szymanski Date: Sun, 21 Jun 2026 15:56:24 -0400 Subject: [PATCH] Add contributor templates and update README --- .../default_merge_message/SQUASH_TEMPLATE.md | 6 + .forgejo/issue_template/bug.yml | 67 +++++++++ .forgejo/issue_template/feature.yml | 37 +++++ .forgejo/pull_request_template.md | 25 ++++ CONTRIBUTING.md | 136 ++++++++++++++++++ README.md | 97 +++++++------ 6 files changed, 326 insertions(+), 42 deletions(-) create mode 100644 .forgejo/default_merge_message/SQUASH_TEMPLATE.md create mode 100644 .forgejo/issue_template/bug.yml create mode 100644 .forgejo/issue_template/feature.yml create mode 100644 .forgejo/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.forgejo/default_merge_message/SQUASH_TEMPLATE.md b/.forgejo/default_merge_message/SQUASH_TEMPLATE.md new file mode 100644 index 0000000..67aa84d --- /dev/null +++ b/.forgejo/default_merge_message/SQUASH_TEMPLATE.md @@ -0,0 +1,6 @@ +${PullRequestTitle} + +Pull request: (#${PullRequestIndex}) +${ClosingIssues} + +${PullRequestDescription} diff --git a/.forgejo/issue_template/bug.yml b/.forgejo/issue_template/bug.yml new file mode 100644 index 0000000..67a06d8 --- /dev/null +++ b/.forgejo/issue_template/bug.yml @@ -0,0 +1,67 @@ +name: Bug Report +about: Report a defect or unexpected behavior +title: '' +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for reporting! A well-described bug is half-fixed. Please include as much detail as possible. + - type: textarea + id: current + attributes: + label: Current behavior + description: What actually happened? + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should have happened? + validations: + required: true + - type: textarea + id: steps + attributes: + label: Reproduction steps + placeholder: | + 1. Start the app + 2. Navigate to... + 3. Perform action... + 4. Observe error + validations: + required: true + - type: input + id: version + attributes: + label: Version + description: Version number, tag, or commit SHA + placeholder: e.g. v2.1.0 / abcdef1 + validations: + required: true + - type: dropdown + id: os + attributes: + label: Operating system + options: + - Linux + - macOS + - Other + - type: textarea + id: os_details + attributes: + label: OS details + description: If you selected Linux, which distro and version? If Other, please specify which operating system. + placeholder: e.g. Fedora 41, Arch Linux, Ubuntu 24.04, macOS Sequoia… + - type: textarea + id: logs + attributes: + label: Relevant logs / output + render: shell + - type: textarea + id: context + attributes: + label: Additional context + description: Screenshots, related issues, configuration details, etc. diff --git a/.forgejo/issue_template/feature.yml b/.forgejo/issue_template/feature.yml new file mode 100644 index 0000000..1b0fc69 --- /dev/null +++ b/.forgejo/issue_template/feature.yml @@ -0,0 +1,37 @@ +name: Feature Request +about: Propose a new feature or improvement +title: '' +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to suggest a feature! Please fill out the details below. + - type: textarea + id: motivation + attributes: + label: Motivation + description: What use case does this address? Why is this important? + placeholder: As a , I want to so that . + validations: + required: true + - type: textarea + id: proposed + attributes: + label: Proposed behavior + description: Describe how you envision this working. + validations: + required: true + - type: textarea + id: design + attributes: + label: Design / implementation notes + description: Any thoughts on API, UI, or technical approach (optional). + - type: checkboxes + id: contributing + attributes: + label: Contribution + description: Would you be willing to help implement this? + options: + - label: I'd be interested in working on this diff --git a/.forgejo/pull_request_template.md b/.forgejo/pull_request_template.md new file mode 100644 index 0000000..16e559e --- /dev/null +++ b/.forgejo/pull_request_template.md @@ -0,0 +1,25 @@ +## Description + + + +Closes # + +## Type of change + +- [ ] πŸ› Bug fix +- [ ] ✨ New feature +- [ ] ♻️ Refactor / code cleanup +- [ ] πŸ“– Documentation +- [ ] πŸ”§ Dependencies / build tooling + +## How was this tested? + + + +## Checklist + +- [ ] I have read the [contributing guide](CONTRIBUTING.md) +- [ ] My code follows the project's style guidelines +- [ ] I have added or updated tests as needed +- [ ] Documentation has been updated where applicable +- [ ] All existing tests pass diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..13e3b69 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,136 @@ +# Contributing to Luminate + +Thanks for your interest in contributing! πŸŽ‰ + +This document covers the workflow, conventions, and expectations for contributing to Luminate. Please read through before opening issues or pull requests. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Branching](#branching) +- [Issue Templates](#issue-templates) +- [Pull Requests](#pull-requests) +- [Coding Style](#coding-style) +- [Source File Headers](#source-file-headers) +- [Testing](#testing) +- [License](#license) + +## Code of Conduct + +This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All participants, contributors, maintainers, and users are expected to treat each other with respect. Harassment or toxic behavior of any kind will not be tolerated. + +## Getting Started + +1. Ensure you have Swift 6.0+ and a compatible platform (Linux or macOS). +2. Clone the repository. +3. Run `swift build` from the project root to verify your environment. +4. Run `swift test` to confirm all tests pass. + +## Branching + +`main` is the default and release branch. It is **protected**; direct pushes are not permitted. All changes must go through a pull request. + +Branch names must follow one of these prefixes: + +| Prefix | Purpose | +|--------|---------| +| `feature/*` | New features or enhancements | +| `fix/*` | Bug fixes | +| `chore/*` | Maintenance, dependency updates, etc. | +| `refactor/*` | Code restructuring without behavior change | +| `docs/*` | Documentation-only changes | +| `test/*` | Adding or updating tests | +| `perf/*` | Performance improvements | +| `style/*` | Code formatting and style fixes | + +Examples: `feature/episode-detail-screen`, `fix/login-crash`, `chore/bump-dependencies`. + +## Issue Templates + +Please use the provided templates when creating issues: + +- [**Bug Report**](.forgejo/issue_template/bug.yml) - for reporting defects or unexpected behavior +- [**Feature Request**](.forgejo/issue_template/feature.yml) - for proposing new features + +These templates help ensure enough context is captured to act on your report quickly. Labels are applied automatically based on the template used. + +## Pull Requests + +1. Create a branch from `main` following the [branch naming convention](#branching). +2. Make your changes, adhering to the [coding style](#coding-style) and [header format](#source-file-headers). +3. Ensure all tests pass (`swift test`) and the project builds without warnings (`swift build`). +4. Open a pull request against `main` using the [pull request template](.forgejo/pull_request_template.md). +5. A maintainer will review your PR. Expect constructive feedback and possibly requests for changes. +6. Once approved, your PR will be squashed into `main`. + +## Coding Style + +This project uses [swift-format](https://github.com/swiftlang/swift-format) for code formatting. The configuration is defined in [`.swift-format`](.swift-format) at the project root. + +Before submitting, format your code: + +```bash +swift-format format --in-place --recursive Sources/ +``` + +Or check for issues without modifying files: + +```bash +swift-format lint --recursive Sources/ +``` + +Key style rules: + +- 4-space indentation +- 100-column line length +- Semicolons are not allowed +- One variable declaration per line +- Ordered imports +- Lower camel case identifiers +- No block comments (`/* */`); use `//` or `///` instead +- Triple-slash (`///`) for documentation comments +- One case per line in switch statements + +## Source File Headers + +Every Swift source file must begin with the following header, with placeholders replaced as follows: + +- `{{ FILE_NAME }}` - the actual filename +- `{{ YEAR }}` - the file's creation year +- `{{ NAME/USERNAME }}` - your name or username +- `{{ EMAIL }}` - your email address + +```swift +// +// {{ FILE_NAME }}.swift +// +// Copyright {{ YEAR }} {{ NAME/USERNAME }} <{{ EMAIL }}> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// +// SPDX-License-Identifier: GPL-3.0-or-later +// +``` + +## Testing + +- Tests live in `Tests/LuminateTests/` and use the [Swift Testing](https://developer.apple.com/documentation/testing) framework (`@Test`, `#expect`). +- Run the full suite with `swift test`. +- When adding new functionality, include corresponding tests. +- When fixing a bug, consider adding a test that reproduces the issue before applying the fix. + +## License + +By contributing, you agree that your contributions will be licensed under the [GNU General Public License v3.0 or later](LICENSE), the same license as the project. diff --git a/README.md b/README.md index 19f61ab..9a8ca03 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Luminate +# Luminate ✨ -Luminate is a modern and robust Jellyfin client for the Linux desktop. +Luminate is a modern Jellyfin client for the Linux desktop, built with Swift and Adwaita. -It aims to provide an elegant and immersive browsing experience for any Jellyfin server with features rivaling that of the default Jellyfin Media Player, all while feeling right at home in your Linux desktop environment. +It aims to provide a delightful browsing experience for any Jellyfin server with features rivaling the default Jellyfin Media Player, all while feeling right at home in your GNOME desktop. -## Building +## πŸ› οΈ Building ### Linux (Native) @@ -30,7 +30,7 @@ swift build swift run ``` -macOS builds are supported for development but the target platform is Linux/Flatpak. +macOS builds work for development, but the target platform is Linux/Flatpak. ### Release Build @@ -38,50 +38,63 @@ macOS builds are supported for development but the target platform is Linux/Flat swift build -c release ``` -## Contributing +## 🀝 Contributing -Contributions to Luminate are welcome! Refer to the project roadmap below to get an idea of what's currently being worked on before jumping in if you'd like, or you can check out the [current issues](https://git.bscubed.dev/echo/Luminate/issues) for something to tackle. +Contributions are welcome! Check out [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide on branching, coding style, pull requests, and everything you need to get started. You can also browse the [issue tracker](https://git.bscubed.dev/echo/Luminate/issues) for open issues to tackle. -## Project Roadmap +## πŸ—ΊοΈ Project Roadmap -### Implemented Features +### Login -- Server login with Jellyfin authentication -- Persistent session storage (auto-login across restarts) -- Home screen with Continue Watching, Next Up, and Recently Added rows -- Library grid browsing with folder navigation -- Movie detail view (backdrop, poster, metadata, cast, similar items) -- TV show detail view with season picker and episode list -- Search with debounced text input and result display -- Playback recording (start/progress/stop reporting to server) -- Favorites (toggle favorite on movie detail) -- Mark played/unplayed -- Image caching (memory + disk) -- WebSocket client for server events -- Dependency injection system -- Stack-based navigation -- Initial localization support (en/de) +| Feature | Completion | Version | Details | +| :--- | :---: | :--- | :--- | +| Server Authentication | βœ… | v0.1.0 | Login via server URL, username, and password | +| Persistent Session Storage | βœ… | v0.1.0 | Auto-login across restarts via SQLite | +| Multi-User Support | ❌ | | Switch between accounts without re-entering credentials | +| Quick Login | ❌ | | One-click reconnect to recently used servers | -### In Progress +### Libraries -- Video player widget (planned mpv + GtkGLArea integration) -- Connecting detail views to navigation stack -- Migrating library views to `@Injected` dependency injection +| Feature | Completion | Version | Details | +| :--- | :---: | :--- | :--- | +| Home Screen | βœ… | v0.1.0 | Continue Watching, Next Up, and Recently Added rows | +| Library Grid Browsing | βœ… | v0.1.0 | Folder navigation with responsive grid layout | +| Movie Detail View | βœ… | v0.1.0 | Backdrop, poster, metadata, cast, similar items, actions | +| TV Show Detail View | βœ… | v0.1.0 | Season picker, episode list with thumbnails and runtime | +| Search | βœ… | v0.1.0 | Debounced text input with results across libraries | +| Detail View Navigation | 🚧 | v0.1.0 | Connecting poster cells to their detail views | +| Unified Search Integration | ❌ | | Search results navigating directly to content | -### Planned +### Playback -- Real video playback with seeking and progress tracking -- Unified search integration -- Continue Watching resume from home screen -- Keyboard shortcut improvements -- Error handling UI for failed network requests -- Unit and UI testing -- CI/CD pipeline -- Flatpak publishing on Flathub -- Multi-user support -- Offline/download support -- Quick login +| Feature | Completion | Version | Details | +| :--- | :---: | :--- | :--- | +| Playback Progress Reporting | βœ… | v0.1.0 | Start, progress, and stop reported to server | +| Video Player Widget | 🚧 | v0.1.0 | mpv + GtkGLArea integration (placeholder currently) | +| Full Video Playback | ❌ | | Play, pause, seek, progress bar, and fullscreen | +| Resume Playback | ❌ | | Continue Watching from home screen plays at saved position | -## License +### Functionality -GPL-3.0 +| Feature | Completion | Version | Details | +| :--- | :---: | :--- | :--- | +| Favorites | βœ… | v0.1.0 | Toggle favorite status on items | +| Mark Played / Unplayed | βœ… | v0.1.0 | Track watched state | +| Image Caching | βœ… | v0.1.0 | Two-tier cache (memory + disk) with deferred loading | +| WebSocket Client | βœ… | v0.1.0 | Real-time server event notifications | +| Dependency Injection | βœ… | v0.1.0 | `@Injected` property wrapper and `DIContainer` | +| Stack Navigation | βœ… | v0.1.0 | `NavigationView` with typed `NavigationStack` | +| Localization (en/de) | βœ… | v0.1.0 | YAML-based strings with the `localized` package | +| `@Injected` Migration | 🚧 | v0.1.0 | Migrating library views from parameter injection | +| Keyboard Shortcuts | ❌ | | Global shortcuts for search, navigation, playback | +| Error Handling UI | ❌ | | User-facing error states for network failures | +| Testing | ❌ | | Unit and UI test coverage | +| CI/CD Pipeline | ❌ | | Automated builds and test runs | +| Flatpak Publishing | ❌ | | Release on Flathub | +| Offline / Download Support | ❌ | | Cache media for offline playback | + +## πŸ“„ License + +Luminate is free software: you can redistribute it and/or modify it under the terms of the [GNU General Public License](LICENSE) as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [GNU General Public License](LICENSE) for more details.