guiwf/lix

Files

T

eldritch horrorsandjade b0d7a81613 fix tooling after include reorganization

clangd broke because it can't look through symlinks. compile_commands
manipulation does not fix it, clangd configuration does not fix it, a
vfs overlay does not fix it, and while a combination of those can fix
it with a bind mount in place that's just too cursed to even consider

clangd bug: https://github.com/llvm/llvm-project/issues/116877

Change-Id: I8e3e8489548eb3a7aa65ac9d12a5ec8abf814aec

2024-11-19 22:55:32 +00:00

2.4 KiB

Raw Blame History

This section describes the notion of deprecated features, and how it fits into the big picture of the development of Lix.

What are deprecated features?

Deprecated features are disabled by default, with the intent to eventually remove them. Users must explicitly enable them to keep using them, by toggling the associated deprecated feature flags. This allows backwards compatibility and a graceful transition away from undesired features.

Which features can be deprecated?

Undesired features should be soft-deprecated by yielding a warning when used for a significant amount of time before the can be deprecated. Legacy obsolete feature with little to no usage may go through this process faster. Deprecated features should have a migration path to a preferred alternative.

Lifecycle of a deprecated feature

This description is not normative, but a feature removal may roughly happen like this:

Add a warning when the feature is being used.
Disable the feature by default, putting it behind a deprecated feature flag.

If disabling the feature started out as an opt-in experimental feature, turn that experimental flag into a no-op or remove it entirely. For example, --extra-experimental-features=no-url-literals becomes --extra-deprecated-features=url-literals.

Decide on a time frame for how long that feature will still be supported for backwards compatibility, and clearly communicate that in the error messages.

Sometimes, automatic migration to alternatives is possible, and such should be provided if possible
At least one NixOS release cycle should be the minimum

Finally remove the feature entirely, only keeping the error message for those still using it.

Relation to language versioning

Obviously, removing anything breaks backwards compatibility. In an ideal world, we'd have SemVer controls over the language and its features, cleanly allowing us to make breaking changes. See https://wiki.lix.systems/books/lix-contributors/page/language-versioning and RFC 137 for efforts on that. However, we do not live in such an ideal world, and currently this goal is so far away, that "just disable it with some back-compat for a couple of years" is the most realistic solution, especially for comparatively minor changes.

Currently available deprecated features

{{#include @generated@/../../../lix/libutil/deprecated-feature-descriptions.md}}

2.4 KiB Raw Blame History