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
+To test, format, lint, etc that CI would do, install engage, allow the `.envrc`
-# Run tests
+file using `direnv allow`, and run `engage`.
-cargo test
 
-# Check compilation
+All of the tasks are defined at the [engage.toml][engage.toml] file. You can
-cargo check --workspace
+view all of them neatly by running `engage list`
 
-# Run lints
+If you would like to run only a specific engage task group, use `just`:
-cargo clippy --workspace
-# Auto-fix: cargo clippy --workspace --fix --allow-staged;
 
-# Format code (must use nightly)
+- `engage just <group>`
-cargo +nightly fmt
+- 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
+Continuwuity's website uses [`mdbook`][mdbook] and deployed via CI using GitHub
-in the [`documentation.yml`][documentation.yml] workflow file. All documentation is in the `docs/`
+Pages in the [`documentation.yml`][documentation.yml] workflow file with Nix's
-directory at the top level.
+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:
+The output of the mdbook generation is in `result/`. mdbooks can be opened in
-   ```bash
+your browser from the individual HTML files without any web server needed.
-   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.
 
 ### 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
-continuwuity Matrix rooms for Code of Conduct violations.
+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.
+During Continuwuity development, we have had to fork
-These forks exist for various reasons including features that upstream projects won't accept,
+some dependencies to support our use-cases in some areas. This ranges from
-faster-paced development, Continuwuity-specific usecases, or lack of time to upstream changes.
+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):
+- [ruma/ruma][1]: <https://github.com/girlbossceo/ruwuma> - various performance
-
+improvements, more features, faster-paced development, better client/server interop
-- [ruwuma][continuwuation-ruwuma] - Fork of [ruma/ruma][ruma] with various performance improvements, more features and better client/server interop
+hacks upstream won't accept, etc
-- [rocksdb][continuwuation-rocksdb] - Fork of [facebook/rocksdb][rocksdb] via [`@zaidoon1`][8] with liburing build fixes and GCC debug build fixes
+- [facebook/rocksdb][2]: <https://github.com/girlbossceo/rocksdb> - liburing
-- [jemallocator][continuwuation-jemallocator] - Fork of [tikv/jemallocator][jemallocator] fixing musl builds, suspicious code,
+build fixes and GCC debug build fix
-  and adding support for redzones in Valgrind
+- [tikv/jemallocator][3]: <https://github.com/girlbossceo/jemallocator> - musl
-- [rustyline-async][continuwuation-rustyline-async] - Fork of [zyansheep/rustyline-async][rustyline-async] with tab completion callback
+builds seem to be broken on upstream, fixes some broken/suspicious code in
-  and `CTRL+\` signal quit event for Continuwuity console CLI
+places, additional safety measures, and support redzones for Valgrind
-- [rust-rocksdb][continuwuation-rust-rocksdb] - Fork of [rust-rocksdb/rust-rocksdb][rust-rocksdb] fixing musl build issues,
+- [zyansheep/rustyline-async][4]:
-  removing unnecessary `gtest` include, and using our RocksDB and jemallocator forks
+<https://github.com/girlbossceo/rustyline-async> - tab completion callback and
-- [tracing][continuwuation-tracing] - Fork of [tokio-rs/tracing][tracing] implementing `Clone` for `EnvFilter` to
+`CTRL+\` signal quit event for Continuwuity console CLI
-  support dynamically changing tracing environments
+- [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
+[1]: https://github.com/ruma/ruma/
-
+[2]: https://github.com/facebook/rocksdb/
-To build a Docker image for Continuwuity, use the standard Docker build command:
+[3]: https://github.com/tikv/jemallocator/
-
+[4]: https://github.com/zyansheep/rustyline-async/
-```bash
+[5]: https://github.com/rust-rocksdb/rust-rocksdb/
-docker build -f docker/Dockerfile .
+[6]: https://github.com/tokio-rs/tracing/
-```
-
-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/
-
 [7]: https://docs.rs/tokio-console/latest/tokio_console/
 [8]: https://github.com/zaidoon1/
 [9]: https://github.com/rust-lang/cargo/issues/12162