Mirrors/rust-analyzer
2
0
Fork 0
mirror of https://github.com/rust-lang/rust-analyzer synced 2025-01-27 04:15:08 +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. 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 ### Code generation
Some components in this repository are generated through automatic processes. Some components in this repository are generated through automatic processes.