# Contributing to Synvael

Thanks for your interest in contributing to Synvael. This guide covers how contributions work, our expectations, and what you get out of it as a contributor.

## Philosophy

Synvael is **open-source and commercially developed**. The engine code uses the AGPLv3 license, and official game assets use CC-BY-NC-SA 4.0 (check [LICENSE.md](LICENSE.md) for the details). The project is built by Cryoforge Nexus, a commercial company that plans to monetize the finished game.

We welcome and credit outside contributions, but they don't include equity or revenue share. If that arrangement doesn't work for you, it's best not to contribute. We prefer being upfront about this rather than risking anyone feeling misled later on.

## Contributor Tiers

### Core team

The core team handles architectural and roadmap decisions. They are eligible for an ownership stake in Cryoforge Nexus based on the company's internal agreements.

Membership isn't open by default, but there is a way in. A contributor becomes **eligible for consideration** when they meet all these criteria:

1. **Sustained contribution:** At least six months of active, merged contributions. Consistency and quality are more important than sheer volume.
2. **Architectural ownership:** The contributor has taken charge of at least one subsystem (like meshing, networking, worldgen, or a major Lua API surface) and has shown they can make good design decisions there, rather than just completing assigned tasks.
3. **Community trust:** A solid track record of constructive code reviews, issue discussions, and teamwork. No history of conflict or ignoring project norms.

Once these criteria are met, an existing core member can **nominate** the contributor. Joining requires a **supermajority vote** (two-thirds or more) from the current core members, and the nominee is free to decline.

Meeting the criteria just makes someone eligible, not entitled to membership. The final call is a human judgement about long-term fit with the team.

### Outside contributors

This includes anyone who submits a pull request, asset, bug report, translation, or documentation change. Outside contributors get public credit, authorship on their work under our open-source licenses, code reviews, mentorship when helpful, and a voice in technical discussions. They do not get equity, revenue share, or any guarantee of future paid work.

## Contributor License Agreement (CLA)

Every contribution (both code and assets) requires signing a [Contributor License Agreement](CLA.md) before we can merge a pull request. The CLA does **not** transfer your copyright; you keep it. It simply grants Cryoforge Nexus a perpetual, irrevocable license to use, modify, sublicense, and relicense your contribution, including for commercial purposes.

This is necessary because the public licenses (AGPLv3 and CC-BY-NC-SA 4.0) would otherwise block our monetization plan. Without the CLA, contributed assets in particular would prevent the project from having a commercial release.

### How to sign

When you open a pull request, an automated check looks to see if all commit authors have signed the CLA. If not, it drops a comment with instructions. To sign, just leave a comment on the pull request saying:

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

The bot records your signature and updates the check status automatically. You only have to do this once. After that, all future pull requests from your GitHub account are accepted without needing to sign again.

## What is accepted

- **Code** in Rust (for engine crates) or Lua (for `assets/scripts/` and `mods/`), licensed under AGPLv3.
- **Original assets** you created yourself: 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** (like other games, films, or copyrighted art). Everything submitted must be your original work.
- **AI-generated assets.** Textures, models, sounds, icons, and any other non-code assets must be originally made by humans. Check the [AI-Assisted Contributions](#ai-assisted-contributions) section below.
- **Contributions without a signed CLA.** The bot enforces this strictly, so unsigned pull requests won't be merged.
- **Native (Rust) mods submitted as pull requests.** Native mods that link against engine internals are considered derivative works under AGPLv3 and belong in their own separate repositories. Lua mods are completely welcome in `mods/`.

## Coding Standards & Architecture

For the complete technical engineering manual, including architecture boundaries, naming, documentation style, and lint rules, please refer to [DEVELOPMENT.md](DEVELOPMENT.md).

## Pull Request Process

1. **Branch from `dev`.** The `main` branch is kept strictly for stable releases. All active development happens on the **`dev`** branch. If you are working on a large feature, always create a new feature branch off `dev` (for example, `feat/new-worldgen`). Don't commit large, work-in-progress features directly to `dev`.
2. **One concept per pull request.** Try to keep your changes focused. If a pull request touches multiple unrelated systems, please split it up.
3. **Ensure CI passes.** Our pipeline runs `cargo fmt`, `cargo clippy`, `selene`, and `stylua`. Pull requests with lint failures won't be reviewed. Always make sure your code passes these tools locally before pushing.
4. **Sign the CLA.** The CLA bot must show a passing status before we start reviewing.
5. **Describe the change.** Explain what your pull request does, why it's needed, and any design decisions you made. If it relates to any open issues, link them.
6. **Respond to review feedback.** Maintainers might request changes. Please address them or discuss alternative approaches with us.

## Contributing workflow

Before you commit a change, verify it against the actual repo state instead of assuming it's correct. Read the files, inspect `git diff`, and run `cargo check`, `cargo clippy`, or `cargo test` as needed. Then just follow this loop for each change:

1. **Verify** that the change is actually present and correct in your working tree.
2. **Run the linter and formatter** to ensure no regressions or style issues sneaked in: `cargo clippy --all-targets --all-features -- -D warnings`, `cargo fmt --all -- --check`, `selene .`, and `stylua .`.
3. **Ensure useful comments are present** before committing: add function doc comments (`///`) and inline comments above non-obvious logic, sticking to the project's documentation style.
4. **Create a focused git commit** using the commit conventions listed below.

Keep commits scoped to a single concept. Don't bundle multiple unrelated changes into one commit, and try not to leave a verified change uncommitted before moving on to the next thing.

## Commit conventions

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

Format:

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

[optional body]

[optional footer(s)]
```

- **Type** (required, exactly one): `feat` (new feature), `fix` (bug fix), `refactor` (no behaviour change), `perf`, `docs`, `test`, `chore` (build/tooling/deps), `build`, `ci`. If there are breaking changes, append a `!` before the colon: `feat(scripting)!: ...`.
- **Scope** (required): the crate the change primarily affects, choosing from `client`, `server`, `renderer`, `shared`, or `scripting`. If the change spans the whole workspace (like a Cargo config change or `.gitattributes`), use `workspace`. For changes isolated to non-Rust assets, use `assets`. Please avoid omitting the scope and don't make up new scopes per commit.
- **Subject:** imperative mood (use "add", not "added" or "adds"), lowercase, no trailing period, and keep it under 72 characters.
- **Body:** keep commit messages short and sweet. Usually just a subject is fine. The main exception is `fix(...)` commits for non-trivial bugs, where a body explaining the root cause and why the fix actually works is super helpful. There's no need to pad routine commits with bodies.

Examples:

```
feat(scripting): expose blocks.register to lua
fix(renderer): clamp swapchain extent to surface caps
refactor(shared): split network message types into submodule
chore(workspace): bump ash to 0.39
docs(assets): document texture-pack overlay layout
feat(server)!: change tick rate from 20 to 30 Hz
```

If a single commit touches multiple crates and honestly can't be reasonably split, that's usually a sign that it should be split anyway. Only fall back to the `workspace` scope when the change is fundamentally workspace-wide.

## Recognition

Every merged contribution gets an entry in `CREDITS.md`. Major or sustained contributions are highlighted on the project website. Standout contributors might be offered paid bounties for specific scoped work once the project starts generating revenue. This is a transactional setup, not equity or an ongoing revenue share.

This is the hard limit of what outside contribution earns. If your goal is co-ownership of a game studio, this project probably isn't the right fit.

## AI-Assisted Contributions

You are welcome to use AI tools like code completion, generation, or refactoring assistants when writing code. Just keep these rules in mind:

- **AI-assisted code is accepted, with conditions.** You must genuinely review every line of the submitted code and be able to explain what it does and why. If you can't answer questions about your own code during review, the contribution will be rejected. You are the responsible author, not the AI tool.
- **AI-generated assets are not accepted.** Textures, models, sounds, icons, and other non-code assets must be original human-authored work. This rule applies regardless of the tool used or where its training data came from.
- **Disclosure is required.** If you used AI tools in a meaningful way to create a code contribution, state this in the pull request description. A quick note like "AI-assisted: used Copilot for boilerplate generation" is completely fine.

## Questions?

Feel free to open an issue or start a discussion on the repository. Maintainers are always happy to help with setup, answer questions about the architecture, or chat about proposed changes before you start working on them.