Synvael/CONTRIBUTING.md

# Contributing to Synvael

Thank you for your interest in contributing to Synvael. This document explains how contributions work, what is expected, and what contributors receive in return.

## Philosophy

Synvael is **open-source and commercially developed**. The engine source code is licensed under AGPLv3, official game assets under CC-BY-NC-SA 4.0 (see [LICENSE.md](LICENSE.md) for full terms), and the project is built by Cryoforge Nexus, a commercial entity that intends to monetize the finished game.

Outside contributions are welcome and credited, but they do not carry equity or revenue share. If that trade does not work for you, please do not contribute. The project would rather be upfront about these terms than have anyone feel misled later.

## Contributor Tiers

### Core team

The core team makes architectural and roadmap decisions and is eligible for an ownership stake in Cryoforge Nexus, subject to the company's internal agreements.

Membership is not open by default, but there is a path in. A contributor becomes **eligible for consideration** when all of the following are met:

1. **Sustained contribution.** At least six months of active, merged contributions. Consistency and quality matter more than volume.
2. **Architectural ownership.** The contributor has taken responsibility for at least one subsystem (meshing, networking, worldgen, a major Lua API surface, etc.) and has demonstrated the ability to make sound design decisions within it, not just implement assigned tasks.
3. **Community trust.** A track record of constructive code reviews, issue discussions, and collaboration. No pattern of conflict or disregard for project norms.

When these criteria are met, an existing core member may **nominate** the contributor. Admission requires a **supermajority vote** (two-thirds or more) of current core members. The nominee may decline.

Meeting the criteria makes someone eligible for consideration, not entitled to membership. The final decision remains a human judgement about long-term fit with the team.

### Outside contributors

Anyone who submits a pull request, asset, bug report, translation, or documentation change. Outside contributors receive public credit, authorship on their work under the project's open-source licenses, code review, mentorship where useful, and a voice in technical discussion. They do not receive equity, revenue share, or a guarantee of future paid work.

## Contributor License Agreement (CLA)

Every contribution, code and assets alike, requires signing a [Contributor License Agreement](CLA.md) before a pull request can be merged. The CLA does **not** transfer copyright, contributors retain it. It grants Cryoforge Nexus a perpetual, irrevocable license to use, modify, sublicense, and relicense the contribution, including under commercial terms.

This is necessary because the public licenses (AGPLv3 + CC-BY-NC-SA 4.0) would otherwise prevent the planned monetization model. Without the CLA, contributed assets in particular would lock the project out of any commercial release.

### How to sign

When a pull request is opened, an automated check verifies whether all commit authors have signed the CLA. If not, it posts a comment with instructions. To sign, leave a comment on the pull request containing:

```
I have read the CLA and I agree
```

The bot records the signature and updates the check status automatically. Signing is a one-time action; once recorded, all future pull requests from the same GitHub account are accepted without re-signing.

## What is accepted

- **Code** in Rust (for engine crates) or Lua (for `assets/scripts/` and `mods/`), licensed under AGPLv3.
- **Original assets** authored by the contributor: textures, models, sounds, icons, shaders. Licensed under CC-BY-NC-SA 4.0.
- **Translations, documentation, bug reports, and design feedback.**

## What is not accepted

- **Assets derived from copyrighted third-party material** (other games, films, copyrighted art). All submitted assets must be original work.
- **AI-generated assets.** Textures, models, sounds, icons, and other non-code assets must be original human-authored work. See [AI-Assisted Contributions](#ai-assisted-contributions) below.
- **Contributions without a signed CLA.** The bot enforces this; unsigned pull requests cannot be merged.
- **Native (Rust) mods submitted as pull requests.** Native mods that link against engine internals are derivative works under AGPLv3 and belong in their own repositories. Lua mods are welcome in `mods/`.

## Development Setup

### Prerequisites

- [Rust](https://www.rust-lang.org/tools/install) (stable toolchain, edition 2024)
- [Git LFS](https://git-lfs.com/) (binary assets are tracked via LFS)
- A Vulkan-capable GPU with up-to-date drivers (Linux or Windows)

### Building

```bash
git clone https://github.com/Cryoforge-Nexus/Synvael.git
cd Synvael
git lfs pull
cargo build
```

### Running

```bash
cargo run -p client    # windowed client
cargo run -p server    # dedicated server
```

### Testing

```bash
cargo test             # all tests
cargo test -p shared   # tests for a single crate
```

### Linting

The CI pipeline enforces strict linting. Run these locally before pushing:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
selene .
stylua .
```

Lua linting requires [Selene](https://kampfkarren.github.io/selene/) and [StyLua](https://github.com/JohnnyMorganz/StyLua). Install them via `cargo install selene` and `cargo install stylua`, or use the pre-built binaries from their release pages.

## Coding Standards

All conventions, commit format, documentation style, naming, architecture boundaries and lint rules are documented in [AGENTS.md](AGENTS.md). That file is the single source of truth; this section highlights the most relevant points for contributors.

### Commit format

[Conventional Commits](https://www.conventionalcommits.org/) with a mandatory crate-name scope:

```
<type>(<crate>): <imperative subject>
```

Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`. Scope is the primary crate affected (`client`, `server`, `renderer`, `shared`, `scripting`) or `workspace` / `assets` for cross-cutting changes.

Examples:

```
feat(scripting): expose blocks.register to lua
fix(renderer): clamp swapchain extent to surface caps
docs(assets): document texture-pack overlay layout
```

### Documentation

- Formal, objective tone. No first-person or second-person pronouns.
- Every public struct field requires a `///` doc comment.
- Inline comments (`//`) above non-obvious logic.

### Architecture boundaries

- Protocol/data types → `shared`
- Lua API and `mlua` integration → `scripting`
- GPU/draw code → `renderer`
- Input, windowing, presentation → `client`
- Simulation, authoritative logic → `server`

Do not place simulation logic in `client`. See [AGENTS.md](AGENTS.md) for the full rationale.

## Pull Request Process

1. **Branch from `dev`.** The `main` branch is reserved for stable releases. All development happens on `dev`. For any feature of non-trivial scope, create a feature branch off `dev` (e.g., `feat/new-worldgen`).
2. **One concept per pull request.** Keep changes focused. If a pull request touches multiple unrelated systems, split it.
3. **Ensure CI passes.** The pipeline runs `cargo fmt`, `cargo clippy`, `selene`, and `stylua`. Pull requests with lint failures are not reviewed.
4. **Sign the CLA.** The CLA bot must report a passing status before review begins.
5. **Describe the change.** Explain what the pull request does, why it is needed, and any design decisions made. Link to relevant issues if applicable.
6. **Respond to review feedback.** Maintainers may request changes. Please address them or discuss alternatives.

## Recognition

Every merged contribution earns an entry in `CREDITS.md`. Substantial or sustained contributions are highlighted on the project website. Standout contributors may, once the project has revenue, be offered paid bounties for specific scoped work, this is a transactional arrangement, not equity or an ongoing revenue share.

This is the honest ceiling of what outside contribution earns. If the goal is co-ownership of a game studio, this project is not the right fit.

## AI-Assisted Contributions

AI tools (code completion, generation, refactoring assistants) may be used as aids when writing code. The following rules apply:

- **AI-assisted code is accepted, with conditions.** The contributor must have genuinely reviewed every line of the submitted code and be able to explain what it does and why. Contributions where the author cannot answer questions about their own code during review will be rejected. The contributor, not the AI tool, is the responsible author.
- **AI-generated assets are not accepted.** Textures, models, sounds, icons, and other non-code assets must be original human-authored work. This applies regardless of the AI tool or its training-data provenance.
- **Disclosure is required.** If AI tools were used in a material way during the creation of a code contribution, this must be stated in the pull request description. A brief note (e.g., "AI-assisted: used Copilot for boilerplate generation") is sufficient.

## Questions?

Open an issue or start a discussion on the repository. Maintainers are happy to help with setup, answer questions about the architecture, or discuss proposed changes before work begins.