# 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 <https://www.gnu.org/licenses/>.
//
//  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.