Welcome! Thanks for looking into contributing to our project!
# Table of Contents
- [Looking for Help?](#looking-for-help)
- [Documentation](#documentation)
- [Chat Rooms](#chat-rooms)
- [Reporting Issues](#reporting-issues)
- [Submitting Code](#submitting-code)
- [Coding Style](#coding-style)
- [Submitting PRs](#submitting-prs)
- [Where do I start?](#where-do-i-start)
- [Testing](#testing)
- [LLM Contributions](#llm-contributions)
- [Project-related use of LLMs](#project-related-use-of-llms)
# Looking for Help?
Here is a list of helpful resources you can consult:
## Documentation
- [Matrix spec Documentation](https://spec.matrix.org/latest/)
- [Ruma Documentation](https://docs.rs/ruma/latest/ruma/)
## Chat Rooms
- Ruma Matrix room: [#ruma:matrix.org](https://matrix.to/#/#ruma:matrix.org)
- Ruma Development Matrix room: [#ruma-dev:matrix.org](https://matrix.to/#/#ruma-dev:matrix.org)
- Matrix Developer room: [#matrix-dev:matrix.org](https://matrix.to/#/#matrix-dev:matrix.org)
# Reporting Issues
If you find any bugs, inconsistencies or other problems, feel free to submit
a GitHub [issue](https://github.com/ruma/ruma-client/issues/new).
If you have a quick question, it may be easier to leave a message in
[#ruma:matrix.org](https://matrix.to/#/#ruma:matrix.org).
Also, if you have trouble getting on board, let us know so we can help future
contributors to the project overcome that hurdle too.
# Submitting Code
Ready to write some code? Great! Here are some guidelines to follow to
help you on your way:
## Coding Style
In general, try to replicate the coding style that is already present. Specifically:
### Naming
For internal consistency, Ruma uses American spelling for variable names. Names may differ in the
serialized representation, as the Matrix specification has a mix of British and American English.
### Code Formatting and Linting
We use [rustfmt] to ensure consistent formatting code and [clippy] to catch
common mistakes not caught by the compiler as well as enforcing a few custom
code style choices.
```sh
# if you don't have them installed, install or update the nightly toolchain
rustup install nightly
# … and install prebuilt rustfmt and clippy executables (available for most platforms)
rustup component add rustfmt clippy
```
Before committing your changes, run `cargo +nightly fmt` to format the code (if
your editor / IDE isn't set up to run it automatically) and
`cargo +nightly clippy --workspace`¹ to run lints.
¹ If you modified feature-gated code (`#[cfg(feature = "something")]`), you
have to pass `--all-features` or `--features something` to clippy for it to
check that code
[rustfmt]: https://github.com/rust-lang/rustfmt#readme
[clippy]: https://github.com/rust-lang/rust-clippy#readme
### Import Formatting
Organize your imports into three groups separated by blank lines:
1. `std` imports
1. External imports (from other crates)
1. Local imports (`self::`, `super::`, `crate::` and things like `LocalEnum::*`)
For example,
```rust
use std::collections::BTreeMap;
use ruma_common::api::ruma_api;
use super::MyType;
```
### Commit Messages
Write commit messages using the imperative mood, as if completing the sentence:
"If applied, this commit will \_\_\_." For example, use "Fix some bug" instead
of "Fixed some bug" or "Add a feature" instead of "Added a feature".
(Take a look at this
[blog post](https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/)
for more information on writing good commit messages.)
### Tracking Changes
If your changes affect the public API, add an entry about them to the change log
(`CHANGELOG.md`).
## Submitting PRs
Once you're ready to submit your code, create a pull request, and one of our
maintainers will review it. Once your PR has passed review, a maintainer will
merge the request and you're done! 🎉
## Where do I start?
If this is your first contribution to the project, we recommend taking a look
at one of the [open issues][] we've marked for new contributors.
[open issues]: https://github.com/ruma/ruma-client/issues?q=is%3Aissue+is%3Aopen+label%3A"help+wanted"
# Testing
Before committing, run `cargo check` to make sure that your changes can build,
as well as running the formatting and linting tools
[mentioned above](#code-formatting-and-linting).
# LLM Contributions
Contributions must not include content generated by large language models
or other probabilistic tools like ChatGPT, Claude, and Copilot.
This policy exists due to
- ethical concerns about the data gathering for training these models
- the disproportionate use of electricity and water of building / running them
- the potential negative influence of LLM-generated content on quality
- potential copyright violations
This ban of LLM-generated content applies to all parts of the projects,
including, but not limited to, code, documentation, issues, and artworks.
An exception applies for purely translating texts for issues and comments to
English. We may make more exceptions for other accessibility-related uses.
## Project-related use of LLMs
We heavily discourage the use of LLM chat bots as a replacement for reading
Ruma's documentation and API reference.
Support requests referencing misleading or false LLM output relating to the
project may be ignored, since it is a waste of time for us to "debug" where
things went wrong based on this output before human support was sought.