FerrumCFerrumCexperimental
FeaturesBlogDocumentation
GitHub

Contributing

When contributing to this repository, you'll have more luck with getting PRs approved if you come chat with us in the Discord server and let us know about what you are fixing/adding. Keep in mind that clippy, rustfmt and cargo-audit are enforced on CI, so make sure your code passes these checks.

Pull Request Process

  1. Make sure all tests and lints pass. PRs that don't pass CI will be rejected if your code is the cause of the failing tests/lints.
  2. Make sure all needed files are also included and not using absolute paths.
  3. Include a sufficient explanation of your PR. What is it adding/fixing, why does this feature need to be added/fixed, who have you discussed this with, etc. If these questions were answered in a conversation on Discord, mention who you talked with and what consensus was reached.
  4. Check again that tests pass.
  5. Check a 3rd time.
  6. Check that Clippy passes with no issues: cargo clippy --all-targets -- -Dwarnings
  7. Check that Rustfmt passes: cargo fmt --all -- --check
  8. Check that Cargo-audit passes: cargo audit
  9. Submit PR.

Project Specific Guidelines

Just some rules to try to keep the repo nice and organized.

Branches

master

This is the main branch. All PRs should be made to this branch. It contains completed features.

feature/feature-name

For developing a feature, branched off of master.

fix/fixed-thing

For fixing bugs, branched off of master.

rework/refactored-thing

Refactoring code. PR goes to master.

housekeeping

For repo-related updates such as README or CI updates.

docs

For documentation-only changes. Branched from master.

Project Layout

+---.etc | Non-code files 
+---.github | GitHub specific files
+---assets | Assets for the Readme
+---scripts | Scripts for the project, usually python or bash
+---src | Source code
| +---bin | The main binary that stitches everything together
| +---lib | The libraries that provide the business logic
| | +---adapters | Adapters and parsers for data formats
| | +---core | The core logic of the application
| | +---derive_macros | Derive macros. Split into directories for each macro
| | +---ecs | The ECS system
| | +---events | The event system
| | +---net | Networking code
| | +---plugins | Plugins interface
| | +---storage | Storage backend
| | +---utils | Utility functions
| | \---world | Code for interacting with the world
| \---tests | Unit tests

If you add a new directory, please add it to the above list along with its purpose.

Code Rules

  • Tests that only generate/dump data must be #[ignore]d.
  • No absolute paths.
  • Avoid chaining ../; use get_root_path() instead.
  • No lazy unwrap(); prefer expect() with detailed messages.
  • Avoid unnecessary cloning.
  • Add new dependencies to the workspace Cargo.toml.
  • Major features should be added as new crates.
  • New sub-crates must define thiserror-based error types.
  • Use Clippy to ensure no lint errors.
  • Use Rustfmt to ensure formatting.
  • Prefer #[expect] over #[allow].
  • Use #[cfg(test)] where appropriate.
  • Add documentation where applicable.
  • Unsafe code must be documented and justified.
  • No IDE folders like .vscode or .idea.
  • Add tests for new features.
  • Add tests that reproduce bugs when fixing them.
  • Your code must be documented.
  • Your code must contain required tests.

Notes on Formatting

Automatic formatting is highly recommended to avoid large clippy fixes at the end of development.