mirror of
https://github.com/leptos-rs/leptos
synced 2024-11-12 23:57:09 +00:00
76 lines
4 KiB
Markdown
76 lines
4 KiB
Markdown
|
# Contributing to Leptos
|
|||
|
|
|
|||
|
|
Thanks for your interesting in contributing to Leptos! This is a truly
|
|||
|
|
community-driven framework, and while we have a central maintainer (@gbj)
|
|||
|
|
large parts of the renderer, reactive system, and server integrations have
|
|||
|
|
all been written by other contributors. Contributions are always welcome.
|
|||
|
|
|
|||
|
|
Participation in this community is governed by a [Code of Conduct](./CODE_OF_CONDUCT.md).
|
|||
|
|
Some of the most active conversations around development take place on our
|
|||
|
|
[Discord server](https://discord.gg/YdRAhS7eQB).
|
|||
|
|
|
|||
|
|
This guide seeks to
|
|||
|
|
|
|||
|
|
- describe some of the framework’s values (in a technical, not an ethical, sense)
|
|||
|
|
- provide a high-level overview of how the pieces of the framework fit together
|
|||
|
|
- orient you to the organization of this repository
|
|||
|
|
|
|||
|
|
## Values
|
|||
|
|
|
|||
|
|
Leptos, as a framework, reflects certain technical values:
|
|||
|
|
|
|||
|
|
- **Expose primitives rather than imposing patterns.** Provide building blocks
|
|||
|
|
that users can combine together to build up more complex behavior, rather than
|
|||
|
|
requiring users follow certain templates, file formats, etc. e.g., components
|
|||
|
|
are defined as functions, rather than a bespoke single-file comonent format.
|
|||
|
|
The reactive system feeds into the rendering system, rather than being defined
|
|||
|
|
by it.
|
|||
|
|
- **Bottom-up over top-down.** If you envision a user’s application as a tree
|
|||
|
|
(like an HTML document), push meaning toward the leaves of the tree. e.g., If data
|
|||
|
|
needs to be loaded, load it in a granular primitive (resources) rather than a
|
|||
|
|
route- or page-level data structure.
|
|||
|
|
- **Performance by default.** When possible, users should only pay for what they
|
|||
|
|
use. e.g., we don’t make all component props reactive by default. This is
|
|||
|
|
because doing so would force the overhead of a reactive prop onto props that don’t
|
|||
|
|
need to be reactive.
|
|||
|
|
- **Full-stack performance.** Performance can’t be limited to a single metric,
|
|||
|
|
whether that’s a DOM rendering benchmark, WASM binary size, or server response
|
|||
|
|
time. Use methods like HTTP streaming and progressive enhancement to enable
|
|||
|
|
applications to load, become interactive, and respond as quickly as possible.
|
|||
|
|
- **Use safe Rust.** There’s no need for `unsafe` Rust in the framework, and
|
|||
|
|
avoiding it at all costs reduces the maintenance and testing burden significantly.
|
|||
|
|
- **Embrace Rust semantics.** Especially in things like UI templating, use Rust
|
|||
|
|
semantics or extend them in a predictable way with control-flow components
|
|||
|
|
rather than overloading the meaning of Rust terms like `if` or `for` in a
|
|||
|
|
framework-speciic way.
|
|||
|
|
- **Enhance ergonomics without obfuscating what’s happening.** This is by far
|
|||
|
|
the hardest to achieve. It’s often the case that adding additional layers to
|
|||
|
|
improve DX (like a custom build tool and starter templates) comes across as
|
|||
|
|
“too magic” to some people who haven’t had to build the same things manually.
|
|||
|
|
When possible, make it easier to see how the pieces fit together, without
|
|||
|
|
sacrificing the improved DX.
|
|||
|
|
|
|||
|
|
## Processes
|
|||
|
|
|
|||
|
|
We do not have PR templates or formal processes for approving PRs. But there
|
|||
|
|
are a few guidelines that will make it a better experience for everyone:
|
|||
|
|
|
|||
|
|
- Run `cargo fmt` before submitting your code.
|
|||
|
|
- Keep PRs limited to addressing one feature or one issue, in general. In some
|
|||
|
|
cases (e.g., “reduce allocations in the reactive system”) this may touch a number
|
|||
|
|
of different areas, but is still conceptually one thing.
|
|||
|
|
- If it’s an unsolicited PR not linked to an open issue, please include a
|
|||
|
|
specific explanation for what it’s trying to achieve. For example: “When I
|
|||
|
|
was trying to deploy my app under _circumstances X_, I found that the way
|
|||
|
|
_function Z_ was implemented caused _issue Z_. This PR should fix that by
|
|||
|
|
_solution._”
|
|||
|
|
- Our CI tests every PR against all the existing examples, sometimes requiring
|
|||
|
|
compilation for both server and client side, etc. It’s thorough but slow. If
|
|||
|
|
you want to run CI locally to reduce frustration, you can do that by installing
|
|||
|
|
`cargo-make` and using `cargo make check && cargo make test && cargo make
|
|||
|
|
check-examples`.
|
|||
|
|
|
|||
|
|
## Architecture
|
|||
|
|
|
|||
|
|
See [ARCHITECTURE.md](./ARCHITECTURE.md).
|