Brendan Szymanski
f374dc663d
Reviewed-on: echo/Luminate#2 Co-authored-by: Brendan Szymanski <hello@bscubed.dev> Co-committed-by: Brendan Szymanski <hello@bscubed.dev>
136 lines
5 KiB
Markdown
136 lines
5 KiB
Markdown
# 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.
|