-
-
Notifications
You must be signed in to change notification settings - Fork 157
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
RFC 137: Set Nix language version in magic comment
- Loading branch information
1 parent
553b132
commit 02e3126
Showing
1 changed file
with
85 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
--- | ||
feature: nix-language-version | ||
start-date: 2022-12-12 | ||
author: @fricklerhandwerk | ||
co-authors: @thufschmitt @Ericson2314 | ||
shepherd-team: | ||
shepherd-leader: | ||
related-issues: https://github.com/NixOS/nix/issues/7255 | ||
--- | ||
|
||
# Summary | ||
[summary]: #summary | ||
|
||
Add a mechanism to determine which version of the Nix language grammar to use for parsing Nix files. | ||
|
||
# Motivation | ||
[motivation]: #motivation | ||
|
||
Currently it's impossible to introduce backwards-incompatible changes to the Nix language without breaking existing setups. | ||
This proposal is an attempt to overcome that limitation. | ||
|
||
# Detailed design | ||
[design]: #detailed-design | ||
|
||
Introduce a magic comment in the first line of a Nix file: | ||
|
||
#? Nix <version> | ||
|
||
where `<version>` is a released version of Nix the given file is known to work with. | ||
|
||
It is left to the implementation how to use this information. | ||
|
||
# Examples and Interactions | ||
[examples-and-interactions]: #examples-and-interactions | ||
|
||
```nix | ||
#? Nix 2.12 | ||
"nothing" | ||
``` | ||
|
||
# Advantages | ||
[advantages]: #advantages | ||
|
||
- Backwards compatible | ||
- Visually unintrusive | ||
- Self-describing and human-readable | ||
- Opt-in until the feature is implemented in Nix *and* the first backwards-incompatible change to the language is introduced. | ||
- Follows a well-known convention of using [magic numbers in files](https://en.m.wikipedia.org/wiki/Magic_number_(programming)#In_files) | ||
- Encourages, but does not require the Nix evaluator to deal with backwards-incompatible changes in a principled manner. | ||
|
||
# Drawbacks | ||
[drawbacks]: #drawbacks | ||
|
||
- The syntax of the magic comment is arbitrary. | ||
- At least one form of comment is forever bound to begin with `#` to maintain compatibility. | ||
- There is a chance of abusing the magic comment for more metadata in the future. | ||
Let's avoid that. | ||
- It requires effort to implement an appropriate system to make use of the version information. | ||
|
||
# Alternatives | ||
[alternatives]: #alternatives | ||
|
||
- Never introduce backwards-incompatible changes to the language. | ||
|
||
This is what has been happening so far, and required additions to be made very carefully. | ||
|
||
- Use a different versioning scheme for the Nix language that is decoupled from the rest of Nix. | ||
|
||
Although this can be done at any point in the future, because it's the evaluator that will read this information. | ||
|
||
- Use a magic string that is incompatible with evaluators prior to the feature, e.g. `%? Nix <version>`. | ||
|
||
This would make clear to users that the file is not intended to be used without explicit handling of compatibility. | ||
Such a breaking change could be reserved for later iterations of how Nix encodes language version information. | ||
|
||
# Unresolved questions | ||
[unresolved]: #unresolved-questions | ||
|
||
- Is the proposed magic number already in use in [other file formats](https://en.m.wikipedia.org/wiki/Magic_number_(programming)#In_files)? | ||
- Should we allow multiple known-good versions in one line? | ||
|
||
# Future work | ||
[future]: #future-work | ||
|
||
Determine what exaclty to do with the information given in the magic comment. |