Mirrors/rust-analyzer
2
0
Fork 0
mirror of https://github.com/rust-lang/rust-analyzer synced 2025-01-12 21:28:51 +00:00
Code Issues Projects Releases Packages Wiki Activity

doc: document absence of stability guarantees

Browse source
This commit is contained in:
Aleksey Kladov 2021-11-22 13:06:37 +03:00
parent 183ef048f6
commit d9dc925c2e
1 changed files with 26 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
docs/dev/architecture.md
View file

@ -306,6 +306,32 @@ This crate contains utilities for CPU and memory profiling.
This sections talks about the things which are everywhere and nowhere in particular.
### Stability Guarantees
One of the reasons rust-analyzer moves relatively fast is that we don't introduce new stability guarantees.
Instead, as much as possible we leverage existing ones.
Examples:
* The `ide` API of rust-analyzer are explicitly unstable, but the LSP interface is stable, and here we just implement a stable API managed by someone else.
* Rust language and Cargo are stable, and they are the primary inputs to rust-analyzer.
* The `rowan` library is published to crates.io, but it is deliberately kept under `1.0` and always makes semver-incompatible upgrades
Another important example is that rust-analyzer isn't run on CI, so, unlike `rustc` and `clippy`, it is actually ok for us to change runtime behavior.
At some point we might consider opening up APIs or allowing crates.io libraries to include rust-analyzer specific annotations, but that's going to be a big commitment on our side.
Exceptions:
* `rust-project.json` is a de-facto stable format for non-cargo build systems.
It is probably ok enough, but was definitely stabilized implicitly.
Lesson for the future: when designing API which could become a stability boundary, don't wait for the first users until you stabilize it.
By the time you have first users, it is already de-facto stable.
And the users will first use the thing, and *then* inform you that now you have users.
The sad thing is that stuff should be stable before someone uses it for the first time, or it should contain explicit opt-in.
* We ship some LSP extensions, and we try to keep those somewhat stable.
Here, we need to work with a finite set of editor maintainers, so not providing rock-solid guarantees works.
### Code generation
Some components in this repository are generated through automatic processes.