mirror of
https://forgejo.ellis.link/continuwuation/continuwuity.git
synced 2025-09-10 11:32:49 +02:00
docs: Update contributing guide
This commit is contained in:
parent
2ecbd75d64
commit
4f174324ba
2 changed files with 86 additions and 82 deletions
|
@ -1,6 +1,6 @@
|
|||
# Contributing guide
|
||||
|
||||
This page is for about contributing to Continuwuity. The
|
||||
This page is 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** `cargo fmt`. A lot of the
|
||||
and your code is formatted via the **nightly** rustfmt (`cargo +nightly 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,67 +21,62 @@ 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 CI tests locally
|
||||
### Running tests locally
|
||||
|
||||
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.
|
||||
Tests, compilation, and linting can be run with standard Cargo commands:
|
||||
|
||||
To test, format, lint, etc that CI would do, install engage, allow the `.envrc`
|
||||
file using `direnv allow`, and run `engage`.
|
||||
```bash
|
||||
# Run tests
|
||||
cargo test
|
||||
|
||||
All of the tasks are defined at the [engage.toml][engage.toml] file. You can
|
||||
view all of them neatly by running `engage list`
|
||||
# Check compilation
|
||||
cargo check --workspace
|
||||
|
||||
If you would like to run only a specific engage task group, use `just`:
|
||||
# Run lints
|
||||
cargo clippy --workspace
|
||||
# Auto-fix: cargo clippy --workspace --fix --allow-staged;
|
||||
|
||||
- `engage just <group>`
|
||||
- Example: `engage just lints`
|
||||
# Format code (must use nightly)
|
||||
cargo +nightly fmt
|
||||
```
|
||||
|
||||
If you would like to run a specific engage task in a specific group, use `just
|
||||
<GROUP> [TASK]`: `engage just lints cargo-fmt`
|
||||
### Building Docker images
|
||||
|
||||
The following binaries are used in [`engage.toml`][engage.toml]:
|
||||
Docker images can be built using the standard Docker build command:
|
||||
|
||||
- [`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`
|
||||
```bash
|
||||
docker build -f docker/Dockerfile .
|
||||
```
|
||||
|
||||
The Docker image can be cross-compiled for different architectures if needed.
|
||||
|
||||
### Matrix tests
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
If you'd like to run Complement locally using Nix, see the
|
||||
[testing](development/testing.md) page.
|
||||
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.
|
||||
|
||||
[Sytest][sytest] support will come soon.
|
||||
[Sytest][sytest] is currently unsupported.
|
||||
|
||||
### Writing documentation
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
To build the documentation using Nix, run: `bin/nix-build-and-cache just .#book`
|
||||
To build the documentation locally:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### Inclusivity and Diversity
|
||||
|
||||
|
@ -132,13 +127,6 @@ 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
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue