Skip to content
This repository was archived by the owner on Aug 8, 2026. It is now read-only.

docs: Matron context in README + Matron-specific CONTRIBUTING #2

Merged
danbarker merged 2 commits into from
Aug 8, 2026
Merged

docs: Matron context in README + Matron-specific CONTRIBUTING #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c2858d
docs: explain Matron context, fix ecosystem links, Matron CONTRIBUTING
danbarker Jul 13, 2026
4050b39
docs: update matron-iOS-app references to matron-apple
danbarker Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 23 additions & 130 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,140 +1,33 @@
# Contributing guide
# Contributing to Matron Server

If you would like to work on an [issue][issues] that is not assigned, preferably
ask in the Matrix room first at [#tuwunel:grin.hu][tuwunel-chat],
and comment on it.
Thanks for your interest in contributing!

## Where to contribute

## Inclusivity and Diversity
Contributions are handled through GitHub on
[Matronhq/matron-server](https://github.com/Matronhq/matron-server):

All **MUST** code and write with inclusivity and diversity in mind. See the
[following page by Google on writing inclusive code and
documentation](https://developers.google.com/style/inclusive-documentation).
- **Bugs and feature requests:** open an
[issue](https://github.com/Matronhq/matron-server/issues).
- **Changes:** open a pull request against the `main` branch. Please mark
work-in-progress PRs as drafts.

This **EXPLICITLY** forbids usage of terms like "blacklist"/"whitelist" and
"master"/"slave", [forbids gender-specific words and
phrases](https://developers.google.com/style/pronouns#gender-neutral-pronouns),
forbids ableist language like "sanity-check", "cripple", or "insane", and
forbids culture-specific language (e.g. US-only holidays or cultures).
## Upstream first

No exceptions are allowed. Dependencies that may use these terms are allowed but
[do not replicate the name in your functions or
variables](https://developers.google.com/style/inclusive-documentation#write-around).
Most of the server code in this repository comes from upstream
[Tuwunel](https://github.com/matrix-construct/tuwunel), and this fork is kept
intentionally close to it. Substantive changes to server behavior are usually
better contributed upstream, where they benefit everyone and flow back into
this fork on the next sync. Matron-specific changes here should stay focused
on public metadata, documentation, packaging, and release automation.

In addition to language, write and code with the user experience in mind. This
is software that intends to be used by everyone, so make it easy and comfortable
for everyone to use. 🏳️‍⚧️
## Code standards

Changes must pass the lints (clippy, rustc, rustdoc) and be formatted with the
**nightly** `cargo fmt`, matching upstream Tuwunel's conventions.

## Linting and Formatting
## Licensing

It is mandatory all your changes satisfy the lints (clippy, rustc, rustdoc, etc)
and your code is formatted via the **nightly** `cargo fmt`. A lot of the
`rustfmt.toml` features depend on nightly toolchain. It would be ideal if they
weren't nightly-exclusive features, but they currently still are. CI's rustfmt
uses nightly.

If you need to allow a lint, please make sure it's either obvious as to why
(e.g. clippy saying redundant clone but it's actually required) or it has a
comment saying why. Do not write inefficient code for the sake of satisfying
lints. If a lint is wrong and provides a more inefficient solution or
suggestion, allow the lint and mention that in a comment.


### Variable, comment, function, etc standards

Rust's default style and standards with regards to [function names, variable
names, comments](https://rust-lang.github.io/api-guidelines/naming.html), etc
applies here.


## Software testing

Continuous integration runs [Complement][complement] protocol compliance tests
against Tuwunel. The results are compared against a stored baseline via
`git diff` — both new failures and new passes are flagged. If your changes
affect compliance, note it in your pull request and review the result diff
uploaded as an artifact.

See [Complement Testing](development/testing/complement.md) for details on how
the test harness works and how to run Complement locally against a debug or
release build.


## Writing documentation

Tuwunel's website uses [`mdbook`][mdbook] containing [`rustdoc`][rustdoc]
which are deployed via CI pipeline using GitHub Pages. All documentation is
in the `docs/` directory at the top level. The compiled mdbook website is
also uploaded as an artifact.

- To build the book locally run `mdbook build -d <outdir> .` in the project
root.

- To build the book using local stages of the CI pipeline run
`docker/bake.sh book`; the produced docker image will contain it.

- To build the book using Nix, run: `bin/nix-build-and-cache just .#book`

Rust API documentation (rustdoc) is generated from the sourcecode contained
in `src/` and deployed via CI to a directory within GitHub Pages adjacent to
the book. In other contexts mdbook and rustdoc are independent.

- To build the API documents locally run `cargo doc` and browse to
`target/doc/tuwunel/`.

- To build the API documents using local stages of the CI pipeline run
`docker/bake.sh docs`; the produced docker image will contain results in
`/usr/src/tuwunel/target/x86_64-unknown-linux-gnu/doc` (and one can
extrapolate for other platforms).


## Creating pull requests

Please try to keep contributions to the GitHub. While the mirrors of Tuwunel
allow for pull/merge requests, there is no guarantee I will see them in a timely
manner. Additionally, please mark WIP or unfinished or incomplete PRs as drafts.
This prevents me from having to ping once in a while to double check the status
of it, especially when the CI completed successfully and everything so it
*looks* done.

If you open a pull request on one of the mirrors, it is your responsibility to
inform me about its existence. In the future I may try to solve this with more
repo bots in the Tuwunel Matrix room. There is no mailing list or email-patch
support on the sr.ht mirror, but if you'd like to email me a git patch you can
do so at `jasonzemos@gmail.com`.

Direct all PRs/MRs to the `main` branch.

By sending a pull request or patch, you are agreeing that your changes are
allowed to be licenced under the Apache-2.0 licence and all of your conduct is
in line with the Contributor's Covenant, and Tuwunel's Code of Conduct.

Contribution by users who violate either of these code of conducts will not have
their contributions accepted. This includes users who have been banned from
Tuwunel Matrix rooms for Code of Conduct violations.


## Stale Branch Policy

_This section applies to Matrix-Construct members and Tuwunel maintainers_

Branches on the matrix-construct/tuwunel repository are _centrally maintained_.
They may be rebased without your consent. Trivial conflicts may be resolved by
another maintainer. Please resolve more difficult conflicts as soon as possible.
Stale branches may be deleted in some cases; personal repositories are advised
for avoiding any such complications.

[issues]: https://github.com/matrix-construct/tuwunel/issues
[tuwunel-chat]: https://matrix.to/#/#tuwunel:grin.hu
[complement]: https://github.com/matrix-org/complement/
[sytest]: https://github.com/matrix-org/sytest/
[cargo-deb]: https://github.com/kornelski/cargo-deb
[lychee]: https://github.com/lycheeverse/lychee
[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli
[cargo-audit]: https://github.com/RustSec/rustsec/tree/main/cargo-audit
[direnv]: https://direnv.net/
[mdbook]: https://rust-lang.github.io/mdBook/
[rustdoc]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html
[documentation.yml]: https://github.com/matrix-construct/tuwunel/blob/main/.github/workflows/docs.yml
[rustsdk]: https://github.com/matrix-org/matrix-rust-sdk
By sending a pull request or patch, you agree that your changes may be
licensed under the Apache-2.0 license, and that your conduct is in line with
the [Code of Conduct](CODE_OF_CONDUCT.md).
28 changes: 24 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Matron Server

[Matron](https://matron.chat) is a chat system for talking to Claude Code
agents from your phone, desktop, or browser. This repository is the Matrix
homeserver used by Matron's Matrix transport: clients connect to it over the
Matrix protocol, and [claude-matrix-bridge](https://github.com/Matronhq/claude-matrix-bridge)
relays messages between Matrix rooms and Claude Code sessions.

Matron Server is Matron's Matrix homeserver distribution, tracking
[Tuwunel](https://github.com/matrix-construct/tuwunel) upstream.

Expand All @@ -11,11 +17,13 @@ configuration docs unless a Matron-specific deployment wrapper says otherwise.

| Project | Description |
|---------|-------------|
| [Matron Desktop](https://github.com/matronhq/matron-desktop) | Desktop client |
| [Matron Web](https://github.com/matronhq/matron-web) | Web client |
| [Matron iOS](https://github.com/matronhq/matron-ios) | iOS client |
| [Matron Desktop](https://github.com/Matronhq/matron-desktop) | Desktop client |
| [Matron Web](https://github.com/Matronhq/matron-web) | Web client |
| [Matron iOS](https://github.com/Matronhq/matron-apple) | iOS client |
| **Matron Server** | Matrix homeserver (this repo) |
| [Dev Boxer](https://github.com/matronhq/dev-boxer) | One-command dev environment setup |
| [Matron Journal](https://github.com/Matronhq/matron-journal) | Sync server for Matron's native journal transport |
| [claude-matrix-bridge](https://github.com/Matronhq/claude-matrix-bridge) | Runs Claude Code sessions and bridges them to Matrix and the journal |
| [Dev Boxer](https://github.com/Matronhq/dev-boxer) | One-command dev environment setup |

## Upstream

Expand Down Expand Up @@ -45,6 +53,18 @@ docker run -d \
ghcr.io/matronhq/matron-server:latest
```

## Build from source

The crate and binary are still named `tuwunel` (see [Upstream](#upstream)):

```bash
cargo build --release
```

The resulting binary is at `target/release/tuwunel`. For toolchain details,
feature flags, and deeper build documentation, see the upstream
[Tuwunel docs](https://matrix-construct.github.io/tuwunel/).

## Configuration

Most operators should follow the upstream
Expand Down