CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing guide
 
-This page is about contributing to Continuwuity. The
+This page is for about contributing to Continuwuity. The
 [development](./development.md) page may be of interest for you as well.
 
 If you would like to work on an [issue][issues] that is not assigned, preferably
@@ -10,7 +10,7 @@ and comment on it.
 ### Linting and Formatting
 
 It is mandatory all your changes satisfy the lints (clippy, rustc, rustdoc, etc)
-and your code is formatted via the **nightly** rustfmt (`cargo +nightly fmt`). A lot of the
+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.
@@ -21,52 +21,67 @@ 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.
 
-### Running tests locally
+### Running CI tests locally
 
-Tests, compilation, and linting can be run with standard Cargo commands:
+continuwuity's CI for tests, linting, formatting, audit, etc use
+[`engage`][engage]. engage can be installed from nixpkgs or `cargo install
+engage`. continuwuity's Nix flake devshell has the nixpkgs engage with `direnv`.
+Use `engage --help` for more usage details.
 
-```bash
-# Run tests
-cargo test
+To test, format, lint, etc that CI would do, install engage, allow the `.envrc`
+file using `direnv allow`, and run `engage`.
 
-# Check compilation
-cargo check --workspace
+All of the tasks are defined at the [engage.toml][engage.toml] file. You can
+view all of them neatly by running `engage list`
 
-# Run lints
-cargo clippy --workspace
-# Auto-fix: cargo clippy --workspace --fix --allow-staged;
+If you would like to run only a specific engage task group, use `just`:
 
-# Format code (must use nightly)
-cargo +nightly fmt
-```
+- `engage just <group>`
+- Example: `engage just lints`
+
+If you would like to run a specific engage task in a specific group, use `just
+<GROUP> [TASK]`: `engage just lints cargo-fmt`
+
+The following binaries are used in [`engage.toml`][engage.toml]:
+
+- [`engage`][engage]
+- `nix`
+- [`direnv`][direnv]
+- `rustc`
+- `cargo`
+- `cargo-fmt`
+- `rustdoc`
+- `cargo-clippy`
+- [`cargo-audit`][cargo-audit]
+- [`cargo-deb`][cargo-deb]
+- [`lychee`][lychee]
+- [`markdownlint-cli`][markdownlint-cli]
+- `dpkg`
 
 ### Matrix tests
 
-Continuwuity uses [Complement][complement] for Matrix protocol compliance testing. Complement tests are run manually by developers, and documentation on how to run these tests locally is currently being developed.
+CI runs [Complement][complement], but currently does not fail if results from
+the checked-in results differ with the new results. If your changes are done to
+fix Matrix tests, note that in your pull request. If more Complement tests start
+failing from your changes, please review the logs (they are uploaded as
+artifacts) and determine if they're intended or not.
 
-If your changes are done to fix Matrix tests, please note that in your pull request. If more Complement tests start failing from your changes, please review the logs and determine if they're intended or not.
+If you'd like to run Complement locally using Nix, see the
+[testing](development/testing.md) page.
 
-[Sytest][sytest] is currently unsupported.
+[Sytest][sytest] support will come soon.
 
 ### Writing documentation
 
-Continuwuity's website uses [`mdbook`][mdbook] and is deployed via CI using Cloudflare Pages
-in the [`documentation.yml`][documentation.yml] workflow file. All documentation is in the `docs/`
-directory at the top level.
+Continuwuity's website uses [`mdbook`][mdbook] and deployed via CI using GitHub
+Pages in the [`documentation.yml`][documentation.yml] workflow file with Nix's
+mdbook in the devshell. All documentation is in the `docs/` directory at the top
+level. The compiled mdbook website is also uploaded as an artifact.
 
-To build the documentation locally:
+To build the documentation using Nix, run: `bin/nix-build-and-cache just .#book`
 
-1. Install mdbook if you don't have it already:
-   ```bash
-   cargo install mdbook # or cargo binstall, or another method
-   ```
-
-2. Build the documentation:
-   ```bash
-   mdbook build
-   ```
-
-The output of the mdbook generation is in `public/`. You can open the HTML files directly in your browser without needing a web server.
+The output of the mdbook generation is in `result/`. mdbooks can be opened in
+your browser from the individual HTML files without any web server needed.
 
 ### Inclusivity and Diversity
 
@@ -110,13 +125,20 @@ 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 continuwuity's Code of Conduct.
 
-Contribution by users who violate either of these code of conducts may not have
+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
 continuwuityMatrix rooms for Code of Conduct violations.
 
 [issues]: https://forgejo.ellis.link/continuwuation/continuwuity/issues
 [continuwuity-matrix]: https://matrix.to/#/#continuwuity:continuwuity.org
 [complement]: https://github.com/matrix-org/complement/
+[engage.toml]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/engage.toml
+[engage]: https://charles.page.computer.surgery/engage/
 [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/
 [documentation.yml]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/.forgejo/workflows/documentation.yml

docs/development.md

@@ -68,22 +68,31 @@ do this if Rust supported workspace-level features to begin with.
 
 ## List of forked dependencies
 
-During Continuwuity (and prior projects) development, we have had to fork some dependencies to support our use-cases.
-These forks exist for various reasons including features that upstream projects won't accept,
-faster-paced development, Continuwuity-specific usecases, or lack of time to upstream changes.
+During Continuwuity development, we have had to fork
+some dependencies to support our use-cases in some areas. This ranges from
+things said upstream project won't accept for any reason, faster-paced
+development (unresponsive or slow upstream), Continuwuity-specific usecases, or
+lack of time to upstream some things.
 
-All forked dependencies are maintained under the [continuwuation organization on Forgejo](https://forgejo.ellis.link/continuwuation):
-
-- [ruwuma][continuwuation-ruwuma] - Fork of [ruma/ruma][ruma] with various performance improvements, more features and better client/server interop
-- [rocksdb][continuwuation-rocksdb] - Fork of [facebook/rocksdb][rocksdb] via [`@zaidoon1`][8] with liburing build fixes and GCC debug build fixes
-- [jemallocator][continuwuation-jemallocator] - Fork of [tikv/jemallocator][jemallocator] fixing musl builds, suspicious code,
-  and adding support for redzones in Valgrind
-- [rustyline-async][continuwuation-rustyline-async] - Fork of [zyansheep/rustyline-async][rustyline-async] with tab completion callback
-  and `CTRL+\` signal quit event for Continuwuity console CLI
-- [rust-rocksdb][continuwuation-rust-rocksdb] - Fork of [rust-rocksdb/rust-rocksdb][rust-rocksdb] fixing musl build issues,
-  removing unnecessary `gtest` include, and using our RocksDB and jemallocator forks
-- [tracing][continuwuation-tracing] - Fork of [tokio-rs/tracing][tracing] implementing `Clone` for `EnvFilter` to
-  support dynamically changing tracing environments
+- [ruma/ruma][1]: <https://github.com/girlbossceo/ruwuma> - various performance
+improvements, more features, faster-paced development, better client/server interop
+hacks upstream won't accept, etc
+- [facebook/rocksdb][2]: <https://github.com/girlbossceo/rocksdb> - liburing
+build fixes and GCC debug build fix
+- [tikv/jemallocator][3]: <https://github.com/girlbossceo/jemallocator> - musl
+builds seem to be broken on upstream, fixes some broken/suspicious code in
+places, additional safety measures, and support redzones for Valgrind
+- [zyansheep/rustyline-async][4]:
+<https://github.com/girlbossceo/rustyline-async> - tab completion callback and
+`CTRL+\` signal quit event for Continuwuity console CLI
+- [rust-rocksdb/rust-rocksdb][5]:
+<https://github.com/girlbossceo/rust-rocksdb-zaidoon1> - [`@zaidoon1`][8]'s fork
+has quicker updates, more up to date dependencies, etc. Our fork fixes musl build
+issues, removes unnecessary `gtest` include, and uses our RocksDB and jemallocator
+forks.
+- [tokio-rs/tracing][6]: <https://github.com/girlbossceo/tracing> - Implements
+`Clone` for `EnvFilter` to support dynamically changing tracing envfilter's
+alongside other logging/metrics things
 
 ## Debugging with `tokio-console`
 
@@ -104,30 +113,12 @@ You will also need to enable the `tokio_console` config option in Continuwuity w
 starting it. This was due to tokio-console causing gradual memory leak/usage
 if left enabled.
 
-## Building Docker Images
-
-To build a Docker image for Continuwuity, use the standard Docker build command:
-
-```bash
-docker build -f docker/Dockerfile .
-```
-
-The image can be cross-compiled for different architectures.
-
-[continuwuation-ruwuma]: https://forgejo.ellis.link/continuwuation/ruwuma
-[continuwuation-rocksdb]: https://forgejo.ellis.link/continuwuation/rocksdb
-[continuwuation-jemallocator]: https://forgejo.ellis.link/continuwuation/jemallocator
-[continuwuation-rustyline-async]: https://forgejo.ellis.link/continuwuation/rustyline-async
-[continuwuation-rust-rocksdb]: https://forgejo.ellis.link/continuwuation/rust-rocksdb
-[continuwuation-tracing]: https://forgejo.ellis.link/continuwuation/tracing
-
-[ruma]: https://github.com/ruma/ruma/
-[rocksdb]: https://github.com/facebook/rocksdb/
-[jemallocator]: https://github.com/tikv/jemallocator/
-[rustyline-async]: https://github.com/zyansheep/rustyline-async/
-[rust-rocksdb]: https://github.com/rust-rocksdb/rust-rocksdb/
-[tracing]: https://github.com/tokio-rs/tracing/
-
+[1]: https://github.com/ruma/ruma/
+[2]: https://github.com/facebook/rocksdb/
+[3]: https://github.com/tikv/jemallocator/
+[4]: https://github.com/zyansheep/rustyline-async/
+[5]: https://github.com/rust-rocksdb/rust-rocksdb/
+[6]: https://github.com/tokio-rs/tracing/
 [7]: https://docs.rs/tokio-console/latest/tokio_console/
 [8]: https://github.com/zaidoon1/
 [9]: https://github.com/rust-lang/cargo/issues/12162