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.
Jade added 4 commits 2025-07-01 23:46:42 +00:00
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
Jade added 2 commits 2025-07-02 17:34:59 +00:00
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
nex added the
Documentation
label 2025-07-06 13:31:02 +00:00
Jade force-pushed jade/docs-updates-20250701 from 823c73f480 to ad4651167a 2025-07-14 19:24:39 +00:00 Compare
Jade added 1 commit 2025-07-15 13:48:36 +00:00
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 to 0a8c13ffd2 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
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.