Contributing guidelines

These guidelines apply to all mautrix bridges, as well as other associated projects like the mautrix libraries, meowlnir, and gomuks.

Making pull requests

For any non-trivial changes (more than a few lines), you should join the Matrix room linked in the project readme and briefly explain your plan to confirm that it makes sense and is wanted. Failure to do so may result the PRs in being ignored and/or closed without further comment. The Matrix room is also preferred in case discussion about the contribution beyond basic code review is necessary.

Updating the changelog file is not necessary when making a pull request. That will be done separately when a release is being made.

Pull requests may be missed and/or forgotten for extended periods of time, especially if they involve more complicated changes. Feel free to remind us in the appropriate Matrix room if it seems like nothing is happening. Pinging on GitHub is not recommended.

In case a PR has too many things to fix, it may be rewritten instead of reviewed. If that is something which would offend you, please don't open a PR.

Development instructions

The latest version of Go is recommended, but using the previous version is fine too. Go only supports the last two releases, so anything older than that is EOL and will not work.

Since the bridges use cgo, you'll also need a C compiler and libolm-dev installed (though libolm-dev can be bypassed by using -tags goolm). For Signal, you can either install Rust, or just download libsignal_ffi.a from the CI to avoid the Rust dependency (see normal Signal setup instructions for that).

You should install pre-commit and run pre-commit install in the repo before committing to have linters run automatically. You can also run pre-commit run -a before pushing to lint everything. Finally, you can let GitHub actions run the linters for you after pushing, but it's usually more effort to go back and fix things at that point.

Using Linux or macOS is recommended for development. Windows is generally not a supported environment for anything, so WSL is likely necessary if you're running Windows.

A local Synapse instance is useful for testing bridges. Alternatively, you can sign up for Beeper and use bridge-manager to run local bridges against the Beeper servers (there's a convenient --local-dev flag for bbctl run).

Code style

See https://beeper.notion.site/Beeper-Go-Guidelines-ae943532d96f4ad6a614baf836c073eb

Use of AI

In general, you can use AI to help with contributions. However, you must understand all the changes that were made. If you submit PRs that are full of nonsense, they will be closed immediately. All PRs are held to the same (relatively high) standards for code quality, architecture, etc regardless of whether AI is used.

All changes need to be tested manually. AI can't do testing for you, if you ask it'll most likely just make up nonsense about how the change is 100% correct without actually testing anything.

Also, don't use AI for generating pull request descriptions. AI-generated descriptions are long and usually have zero useful information. Even an empty description is better than a long and useless one.