leptos/CONTRIBUTING.md

76 lines
4.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 frameworks 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 component format.
The reactive system feeds into the rendering system, rather than being defined
by it.
- **Bottom-up over top-down.** If you envision a users 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 dont make all component props reactive by default. This is
because doing so would force the overhead of a reactive prop onto props that dont
need to be reactive.
- **Full-stack performance.** Performance cant be limited to a single metric,
whether thats 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.** Theres 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-specific way.
- **Enhance ergonomics without obfuscating whats happening.** This is by far
the hardest to achieve. Its 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 havent 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 its an unsolicited PR not linked to an open issue, please include a
specific explanation for what its 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. Its 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).