docs: add some more conduwuit development info

Signed-off-by: strawberry <strawberry@puppygock.gay>

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing guide
 
 This page is for about contributing to conduwuit. The
-[development](development.md) page may be of interest for you as well.
+[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
 ask in the Matrix room first at [#conduwuit:puppygock.gay][conduwuit-matrix],
@@ -67,7 +67,7 @@ failing from your changes, please review the logs (they are uploaded as
 artifacts) and determine if they're intended or not.
 
 If you'd like to run Complement locally using Nix, see the
-[testing](docs/development/testing.md) page.
+[testing](development/testing.md) page.
 
 [Sytest][sytest] support will come soon.
 
@@ -128,7 +128,10 @@ 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.
+in line with the Contributor's Covenant, and conduwuit's Code of Conduct.
+
+Contribution by users who violate either of these code of conducts will not have
+their contributions accepted.
 
 [issues]: https://github.com/girlbossceo/conduwuit/issues
 [conduwuit-matrix]: https://matrix.to/#/#conduwuit:puppygock.gay

development.md

@@ -0,0 +1 @@
+docs/development.md

docs/contributing.md

@@ -1 +0,0 @@
-{{#include ../CONTRIBUTING.md}}

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/deploying/nixos.md

@@ -1,11 +1,13 @@
 # conduwuit for NixOS
 
-conduwuit can be acquired by [Lix][lix] from various places:
+conduwuit can be acquired by Nix (or [Lix][lix]) from various places:
 
 * The `flake.nix` at the root of the repo
 * The `default.nix` at the root of the repo
 * From conduwuit's binary cache
 
+A community maintained NixOS package is available at [`conduwuit`](https://search.nixos.org/packages?channel=unstable&show=conduwuit&from=0&size=50&sort=relevance&type=packages&query=conduwuit)
+
 A binary cache for conduwuit that the CI/CD publishes to is available at the
 following places (both are the same just different names):
 
@@ -17,24 +19,26 @@ https://attic.kennel.juneis.dog/conduwuit
 conduwuit:BbycGUgTISsltcmH0qNjFR9dbrQNYgdIAcmViSGoVTE=
 ```
 
-The binary caches have been recreated recently due to attic issues. The old
-public keys were:
+The binary caches were recreated some months ago due to attic issues. The old public
+keys were:
 
 ```
 conduit:Isq8FGyEC6FOXH6nD+BOeAA+bKp6X6UIbupSlGEPuOg=
 conduwuit:lYPVh7o1hLu1idH4Xt2QHaRa49WRGSAqzcfFd94aOTw=
 ```
 
-If specifying a URL in your flake, please use the GitHub remote:
-`github:girlbossceo/conduwuit`
 
-The `flake.nix` and `default.nix` do not (currently) provide a NixOS module, so
-(for now) [`services.matrix-conduit`][module] from Nixpkgs should be used to
-configure conduwuit.
+If specifying a Git remote URL in your flake, you can use any remotes that
+are specified on the README (the mirrors), such as the GitHub: `github:girlbossceo/conduwuit`
+
+The `flake.nix` and `default.nix` do not currently provide a NixOS module (contributions
+welcome!), so [`services.matrix-conduit`][module] from Nixpkgs can be used to configure
+conduwuit.
+
+If you want to run the latest code, you should get conduwuit from the `flake.nix`
+or `default.nix` and set [`services.matrix-conduit.package`][package]
+appropriately to use conduwuit instead of Conduit.
 
-If you want to run the latest code, you should get conduwuit from the
-`flake.nix` or `default.nix` and set
-[`services.matrix-conduit.package`][package] appropriately.
 
 [lix]: https://lix.systems/
 [module]: https://search.nixos.org/options?channel=unstable&query=services.matrix-conduit

docs/development.md

@@ -1,10 +1,74 @@
 # Development
 
 Information about developing the project. If you are only interested in using
-it, you can safely ignore this section. If you plan on contributing, see the
-[contributor's guide](contributing.md).
+it, you can safely ignore this page. If you plan on contributing, see the
+[contributor's guide](./contributing.md).
 
-## List of forked dependencies During conduwuit development, we have had to fork
+## conduwuit project layout
+
+conduwuit uses a collection of sub-crates, packages, or workspace members
+that indicate what each general area of code is for. All of the workspace
+members are under `src/`. The workspace definition is at the top level / root
+`Cargo.toml`.
+
+The crate names are generally self-explanatory:
+- `admin` is the admin room
+- `api` is the HTTP API, Matrix C-S and S-S endpoints, etc
+- `core` is core conduwuit functionality like config loading, error definitions,
+global utilities, logging infrastructure, etc
+- `database` is RocksDB methods, helpers, RocksDB config, and general database definitions,
+utilities, or functions
+- `macros` are conduwuit Rust [macros][macros] like general helper macros, logging
+and error handling macros, and [syn][syn] and [procedural macros][proc-macro]
+used for admin room commands and others
+- `main` is the "primary" sub-crate. This is where the `main()` function lives,
+tokio worker and async initialisation, Sentry initialisation, [clap][clap] init,
+and signal handling. If you are adding new [Rust features][features], they *must*
+go here.
+- `router` is the webserver and request handling bits, using axum, tower, tower-http,
+hyper, etc, and the [global server state][state] to access `services`.
+- `service` is the high-level database definitions and functions for data,
+outbound/sending code, and other business logic such as media fetching.
+
+It is highly unlikely you will ever need to add a new workspace member, but
+if you truly find yourself needing to, we recommend reaching out to us in
+the Matrix room for discussions about it beforehand.
+
+The primary inspiration for this design was apart of hot reloadable development,
+to support "conduwuit as a library" where specific parts can simply be swapped out.
+There is evidence Conduit wanted to go this route too as `axum` is technically an
+optional feature in Conduit, and can be compiled without the binary or axum library
+for handling inbound web requests; but it was never completed or worked.
+
+See the Rust documentation on [Workspaces][workspaces] for general questions
+and information on Cargo workspaces.
+
+## Adding compile-time [features][features]
+
+If you'd like to add a compile-time feature, you must first define it in
+the `main` workspace crate located in `src/main/Cargo.toml`. The feature must
+enable a feature in the other workspace crate(s) you intend to use it in. Then
+the said workspace crate(s) must define the feature there in its `Cargo.toml`.
+
+So, if this is adding a feature to the API such as `woof`, you define the feature
+in the `api` crate's `Cargo.toml` as `woof = []`. The feature definition in `main`'s
+`Cargo.toml` will be `woof = ["conduit-api/woof"]`.
+
+The rationale for this is due to Rust / Cargo not supporting
+["workspace level features"][9], we must make a choice of; either scattering
+features all over the workspace crates, making it difficult for anyone to add
+or remove default features; or define all the features in one central workspace
+crate that propagate down/up to the other workspace crates. It is a Cargo pitfall,
+and we'd like to see better developer UX in Rust's Workspaces.
+
+Additionally, the definition of one single place makes "feature collection" in our
+Nix flake a million times easier instead of collecting and deduping them all from
+searching in all the workspace crates' `Cargo.toml`s. Though we wouldn't need to
+do this if Rust supported workspace-level features to begin with.
+
+## List of forked dependencies
+
+During conduwuit 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), conduwuit-specific usecases, or
@@ -53,3 +117,11 @@ RUSTFLAGS="--cfg tokio_unstable" cargo build \
 [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
+[workspaces]: https://doc.rust-lang.org/cargo/reference/workspaces.html
+[macros]: https://doc.rust-lang.org/book/ch19-06-macros.html
+[syn]: https://docs.rs/syn/latest/syn/
+[proc-macro]: https://doc.rust-lang.org/reference/procedural-macros.html
+[clap]: https://docs.rs/clap/latest/clap/
+[features]: https://doc.rust-lang.org/cargo/reference/features.html
+[state]: https://docs.rs/axum/latest/axum/extract/struct.State.html

nix/pkgs/main/cross-compilation-env.nix

@@ -18,7 +18,7 @@ lib.optionalAttrs stdenv.hostPlatform.isStatic {
           [ "-C" "target-cpu=x86-64-v2" ]
         ++ lib.optionals
           stdenv.targetPlatform.isAarch64
-          [ "-C" "target-cpu=cortex-a55" ] # cortex-a55 == ARMv8.2-a
+          [ "-C" "target-cpu=cortex-a53" ] # cortex-a53 == ARMv8-A
         # This disables PIE for static builds, which isn't great in terms
         # of security. Unfortunately, my hand is forced because nixpkgs'
         # `libstdc++.a` is built without `-fPIE`, which precludes us from

nix/pkgs/main/default.nix

@@ -97,7 +97,7 @@ buildDepsOnlyEnv =
         else if stdenv.targetPlatform.isAarch64
         then lib.subtractLists [ "-DPORTABLE=1" ] old.cmakeFlags
         ++ lib.optionals stdenv.targetPlatform.isAarch64 [
-          # cortex-a73 == ARMv8-A
+          # cortex-a53 == ARMv8-A
           "-DPORTABLE=armv8-a"
         ]
         else old.cmakeFlags;
@@ -131,7 +131,7 @@ buildPackageEnv = {
     + lib.optionalString stdenv.targetPlatform.isx86_64
       " -Ctarget-cpu=x86-64-v2"
     + lib.optionalString stdenv.targetPlatform.isAarch64
-      " -Ctarget-cpu=cortex-a73"; # cortex-a73 == ARMv8-A
+      " -Ctarget-cpu=cortex-a53"; # cortex-a53 == ARMv8-A
 };