rustic-rs / dev-docs Goto Github PK

Should be describing certain architectural decisions and giving a graphical overview.

One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project. Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code. This difference might be hard to perceive if you’ve been working with the project for a while.

I find the ARCHITECTURE file to be a low-effort high-leverage way to bridge this gap. As the name suggests, this file should describe the high-level architecture of the project. Keep it short: every recurring contributor will have to read it. Additionally, the shorter it is, the less likely it will be invalidated by some future change. This is the main rule of thumb for ARCHITECTURE — only specify things that are unlikely to frequently change. Don’t try to keep it synchronized with code. Instead, revisit it a couple of times a year.

• bird’s eye overview of the problem being solved
• specify a more-or-less detailed codemap
  • answers: where’s the thing that does X?
  • answers: what does the thing that I am looking at do?
  • A codemap is a map of a country, not an atlas of maps of its states.
  • Use this as a chance to reflect on the project structure.
  • Are the things you want to put near each other in the codemap adjacent when you run tree .?
• describe coarse-grained modules and how they relate to each other
• avoid going into details of how each module works, pull this into separate documents or (better) inline documentation.
• Do name important files, modules, and types.
• Do not directly link them (links go stale).
  • Instead, encourage the reader to use symbol search to find the mentioned entities by name. This doesn’t require maintenance and will help to discover related, similarly named things.
• Explicitly call-out architectural invariants. Often, important invariants are expressed as an absence of something, and it’s pretty hard to divine that from reading the code.
• Point out boundaries between layers and systems as well. A boundary implicitly contains information about the implementation of the system behind it. It even constrains all possible implementations.
• After finishing the codemap, add a separate section on cross-cutting concerns.

https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

Examples:

• https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md
• https://github.com/lemunozm/mailfred/blob/main/docs/architecture.md
• https://github.com/helix-editor/helix/blob/master/docs/architecture.md

Currently, this is being empty: https://github.com/rustic-rs/rustic/blob/main/docs/dev/development_guide.md

As a starter, we should explain the following things:

• how to use just for common commands (#820)
• cargo xtask for coverage reports and installing needed dependencies (#820)
• setting up an IDE (can help with VSCodium) for Rust development
• link to ARCHITECTURE.md (#757) when ready, so devs can get a fast grip to what is where
• tbc

The docs are outdated WRT the release process. They need to be updated also for the release PR usage and there should be a checklist to follow.

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Pending Approval

These branches will be created by Renovate only once you click their checkbox below.

• chore(deps): update actions/configure-pages action to v5

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update actions/checkout digest to a5ac7e5

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

I think it would be nice to package the book with rustic like we do with the config/ directory. For that it would be essential to be able to render the book to pdf and/or epub or some other format that can be viewed by the users without installing a special reader for it.

Read and work in feedback: https://diataxis.fr/