diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d32d8eac90..fe01c27503 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 .` 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). diff --git a/README.md b/README.md index 43a7545d71..8457f2a1e3 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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 @@ -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