docs: Add code style guide #888

Merged
Jade merged 11 commits from jade/docs-updates-20250701 into main 2025-07-16 22:31:40 +00:00
Owner

Expanding on some stuff noted in the development room.

Also improves deployment documentation.

Expanding on some stuff noted in the development room. Also improves deployment documentation.
docs: Add code style guide
All checks were successful
Checks / Prefligit / prefligit (push) Successful in 28s
Checks / Rust / Format (push) Successful in 52s
Documentation / Build and Deploy Documentation (pull_request) Successful in 53s
Checks / Prefligit / prefligit (pull_request) Successful in 27s
Checks / Rust / Clippy (push) Successful in 5m24s
Checks / Rust / Cargo Test (push) Successful in 5m9s
81d013dd61
nex requested changes 2025-07-02 00:14:20 +00:00
Dismissed
CONTRIBUTING.md Outdated
@ -123,4 +106,0 @@
[do not replicate the name in your functions or
variables](https://developers.google.com/style/inclusive-documentation#write-around).
In addition to language, write and code with the user experience in mind. This
Owner

I (personally) think this entire paragraph should be included verbatim in the moved part.

I (personally) think this entire paragraph should be included verbatim in the moved part.
nex marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -36,6 +26,10 @@ You can run these checks locally by installing [prefligit](https://github.com/j1
```bash
# Requires UV:
Owner

Linking to https://docs.astral.sh/uv/getting-started/installation/ too is probably good to reassure paranoid viewers that they aren't expected to just run some random internet script

Linking to https://docs.astral.sh/uv/getting-started/installation/ too is probably good to reassure paranoid viewers that they aren't expected to just run some random internet script
Jade marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -48,6 +42,8 @@ prefligit --all-files
Alternatively, you can use [pre-commit](https://pre-commit.com/):
```bash
# Requires python
Owner

Which python? (3.12 or above? etc)

Which python? (3.12 or above? etc)
Author
Owner

It doesn't say, although 3 would be implied. I don't think it particularly matters, people are gonna install something reasonably up-to-date

It doesn't say, although 3 would be implied. I don't think it particularly matters, people are gonna install something reasonably up-to-date
nex marked this conversation as resolved
@ -0,0 +118,4 @@
Use appropriate log levels:
- `error!`: Unrecoverable errors that affect functionality
- `warn!`: Potentially problematic situations that don't stop execution
Owner

Something more like

potentially problematic situations that might be recoverable, possibly with undesirable side effects or introduced instability into the runtime

"situations that don't stop execution" feels more oriented to applications rather than server daemons - warnings within an environment like ours are totally natural and even expected, this phrasing makes them feel more worrying than they are.

Something more like > potentially problematic situations that might be recoverable, possibly with undesirable side effects or introduced instability into the runtime "situations that don't stop execution" feels more oriented to applications rather than server daemons - warnings within an environment like ours are totally natural and even expected, this phrasing makes them feel more worrying than they are.
Author
Owner

This is in the context of a single request, or server startup. If the request is aborted unexpectedly, error and return. If the request can continue running/executing, warn. Executing does still make sense here IMO.

potentially problematic situations that might be recoverable, possibly with undesirable side effects or introduced instability into the runtime

might be recoverable doesn't always make sense, although the latter bit does a bit

This is in the context of a single request, or server startup. If the request is aborted unexpectedly, error and return. If the request can continue running/executing, warn. Executing does still make sense here IMO. > potentially problematic situations that might be recoverable, possibly with undesirable side effects or introduced instability into the runtime *might be recoverable* doesn't always make sense, although the latter bit does a bit
nex marked this conversation as resolved
@ -0,0 +184,4 @@
Use the `WithLock` trait from `continuwuity-core::utils::with_lock`:
```rs
use continuwuity_core::utils::with_lock::WithLock;
Owner

we haven't renamed the packages yet

we haven't renamed the packages yet
Author
Owner

Me being silly

Me being silly
Jade marked this conversation as resolved
@ -0,0 +205,4 @@
For async contexts, use the async variant:
```rs
use continuwuity_core::utils::with_lock::WithLockAsync;
Owner

see prior

see prior
Jade marked this conversation as resolved
@ -0,0 +318,4 @@
The following types of language are explicitly forbidden in all code, comments, documentation, and commit messages:
**Ableist language:** Avoid terms like "sanity check", "crazy", "insane", "cripple", or "blind to". Use alternatives like "validation", "unexpected", "disable", or "unaware of".
Owner

This is a really difficult thing to enforce, because different cultures consider albeism differently, and there isn't really a concrete definition. If we're going to require this, it should be defined in a more general/broad sense, rather than explicitly listing examples and alternatives.

This is a really difficult thing to enforce, because different cultures consider albeism differently, and there isn't really a concrete definition. If we're going to require this, it should be defined in a more general/broad sense, rather than explicitly listing examples and alternatives.
Author
Owner

FWIW, this is pretty much copied from the linked guidelines. The best you can really do is provide a baseline set of examples and then leave it up to discretion. Some words are obvious, some words require more cultural context/history/etymology to flag.

FWIW, this is pretty much copied from the linked guidelines. The best you can really do is provide a baseline set of examples and then leave it up to discretion. Some words are obvious, some words require more cultural context/history/etymology to flag.
nex marked this conversation as resolved
@ -0,0 +328,4 @@
Use diverse examples in documentation that avoid culturally-specific references, assumptions about user demographics, or unnecessarily gendered language. Design with accessibility and inclusivity in mind by providing clear error messages and considering diverse user needs.
This software is intended to be used by everyone regardless of background, identity, or ability. Write code and documentation that reflects this commitment to inclusivity.
Owner

See above comment in the removed section of CONTRIBUTING.md

See above comment in the removed section of CONTRIBUTING.md
nex marked this conversation as resolved
docs: Fix code examples in style guide
All checks were successful
Checks / Prefligit / prefligit (push) Successful in 40s
Checks / Prefligit / prefligit (pull_request) Successful in 28s
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m2s
Checks / Rust / Format (push) Successful in 1m22s
Checks / Rust / Clippy (push) Successful in 3m12s
Checks / Rust / Cargo Test (push) Successful in 5m53s
823c73f480
Jade force-pushed jade/docs-updates-20250701 from 823c73f480
All checks were successful
Checks / Prefligit / prefligit (push) Successful in 40s
Checks / Prefligit / prefligit (pull_request) Successful in 28s
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m2s
Checks / Rust / Format (push) Successful in 1m22s
Checks / Rust / Clippy (push) Successful in 3m12s
Checks / Rust / Cargo Test (push) Successful in 5m53s
to ad4651167a
All checks were successful
Release Docker Image / define-variables (push) Successful in 12s
Checks / Prefligit / prefligit (push) Successful in 28s
Checks / Prefligit / prefligit (pull_request) Successful in 16s
Checks / Rust / Format (push) Successful in 47s
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m4s
Checks / Rust / Clippy (push) Successful in 3m16s
Checks / Rust / Cargo Test (push) Successful in 11m2s
Release Docker Image / build-image (linux/amd64, release, linux-amd64, base) (push) Successful in 13m39s
Release Docker Image / build-image (linux/arm64, release, linux-arm64, base) (push) Successful in 14m37s
Release Docker Image / merge (push) Successful in 37s
2025-07-14 19:24:39 +00:00
Compare
fix: Use boolean where expected in services
All checks were successful
Release Docker Image / define-variables (push) Successful in 2s
Checks / Prefligit / prefligit (push) Successful in 28s
Checks / Rust / Format (push) Successful in 44s
Checks / Prefligit / prefligit (pull_request) Successful in 29s
Documentation / Build and Deploy Documentation (pull_request) Successful in 52s
Checks / Rust / Clippy (push) Successful in 3m44s
Checks / Rust / Cargo Test (push) Successful in 4m18s
Release Docker Image / build-image (linux/amd64, release, linux-amd64, base) (push) Successful in 10m10s
Release Docker Image / build-image (linux/arm64, release, linux-arm64, base) (push) Successful in 21m26s
Release Docker Image / merge (push) Successful in 25s
22e3a15dc0
Fixes #905
nex approved these changes 2025-07-16 04:43:11 +00:00
Jade force-pushed jade/docs-updates-20250701 from 22e3a15dc0
All checks were successful
Release Docker Image / define-variables (push) Successful in 2s
Checks / Prefligit / prefligit (push) Successful in 28s
Checks / Rust / Format (push) Successful in 44s
Checks / Prefligit / prefligit (pull_request) Successful in 29s
Documentation / Build and Deploy Documentation (pull_request) Successful in 52s
Checks / Rust / Clippy (push) Successful in 3m44s
Checks / Rust / Cargo Test (push) Successful in 4m18s
Release Docker Image / build-image (linux/amd64, release, linux-amd64, base) (push) Successful in 10m10s
Release Docker Image / build-image (linux/arm64, release, linux-arm64, base) (push) Successful in 21m26s
Release Docker Image / merge (push) Successful in 25s
to 0a8c13ffd2
All checks were successful
Checks / Prefligit / prefligit (pull_request) Successful in 27s
Documentation / Build and Deploy Documentation (pull_request) Successful in 50s
Release Docker Image / define-variables (push) Successful in 3s
Checks / Prefligit / prefligit (push) Successful in 15s
Documentation / Build and Deploy Documentation (push) Successful in 33s
Checks / Rust / Format (push) Successful in 38s
Checks / Rust / Clippy (push) Successful in 4m14s
Checks / Rust / Cargo Test (push) Successful in 4m49s
Release Docker Image / build-image (linux/amd64, release, linux-amd64, base) (push) Successful in 12m13s
Release Docker Image / build-image (linux/arm64, release, linux-arm64, base) (push) Successful in 22m29s
Release Docker Image / merge (push) Successful in 18s
2025-07-16 22:27:22 +00:00
Compare
Jade scheduled this pull request to auto merge when all checks succeed 2025-07-16 22:28:39 +00:00
Jade merged commit 0a8c13ffd2 into main 2025-07-16 22:31:40 +00:00
Jade added this to the v0.5.0-rc.7 milestone 2025-07-25 12:45:10 +00:00
Sign in to join this conversation.
No reviewers
nex
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
continuwuation/continuwuity!888
No description provided.