diff --git a/rfcs/0103-flake-labels-metadata.md b/rfcs/0103-flake-labels-metadata.md new file mode 100644 index 000000000..d3482e898 --- /dev/null +++ b/rfcs/0103-flake-labels-metadata.md @@ -0,0 +1,150 @@ +--- +feature: Flakes metadata (Labels) +start-date: 2021-09-02 +author: Bryan Honof +co-authors: (find a buddy later to help out with the RFC) +shepherd-team: (names, to be nominated and accepted by RFC steering committee) +shepherd-leader: (name to be appointed by RFC steering committee) +related-issues: (will contain links to implementation PRs) +--- + +# Summary +[summary]: #summary + +Having a bit more information about what a flake provides could be useful for +identifying, and categorising, the software the flake contains. This way +existing tools like search.nixos.org can use this information for +indexing/searching. + +# Motivation +[motivation]: #motivation + +Just as NixPkgs uses a file structure to categorise software, e.g. +`./pkgs/games/minetest`, labels in a flake could function in the same way. Having +a tag called "games" in a flake that provides the minetest package as example, +will indicate that this flake possibly provides a package that happens to be a +game. + +As mentioned in the summary, one of the use cases could be that of +search.nixos.org. It will also give the user an opportunity to specify what they +think the software's category is. Another use case could be that of NixOps. +Currently, NixOps doesn't use flakes, but shouldn't be too difficult to convert +to one. Once that has happened, a NixOps plugin could identify itself to be a +plugin by providing the labels `plugin` and `nixops`, inside their flake. + +The expected outcome is that flakes will be better identifyable through a simple +interface. + +# Detailed design +[design]: #detailed-design + +The `labels` attribute in a flake should NOT be mandatory, but optional. It is +already possible to add an attribute `labels`, that is a list of strings, since +the `nix` command will ignore this attribute anyways. It would be a nice feature +to have Nix also parse this attribute when calling `nix flake show`, or `nix +flake metadata`. + +## Labels as a way to tell what the flake repository is about + +One site that already uses a sort of tag system is github. When looking at +[the github page for Nix](https://github.com/NixOS/nix), one can see multiple +labels assigned to the repository. Namely: `c-plus-plus`, `package-manager`, +`nix`, `functional-programming`, `declarative-language`. This tells the end-user +what Nix is all about. Without even reading the description, looking into the +source, or `grep`ping my way through the source, I already know it's programmed +in C++, Nix, is about functional- a declarative programming, etc. + +Having labels in flakes would serve the same purpose, quickly identifying what a +repository is all about through the use of keywords. + +## Labels as a way to make looking for flakes easier + +There's an experimental feature over at +[search.nixos.org](https://search.nixos.org/flakes?) that allows a user to +search for flakes. Currently, it's only possible to search by name. Having labels +inside the flake as well would allow the user to provide additional detail +about what they're looking for. Instead of just searching for `minetest`, with +labels the user could also search for `minetest labels:server`, which would return +all the flakes that provide the `minetest` package, and also have `server` in +their labels list. + +## Labels as a way to group related software together + +Currently, there's a lot of software that either extends, or provides libraries +for, already existing packages. Take Python as example. There's many python +packages inside nixpkgs. These packages provide the python interpreter, +packages, libraries, etc. Having a flake that provides packages for +python could have the following labels: `python3`, `python37`, `python39`, +identifying the versions of python it supports, `machine-learning`, identifying +that this flake has something to do with machine learning, and `library`, saying +it's a library for python. + +This mechanism would cause related software to be better identifyable. A user +that sees a flake with labels `python`, and `library`, would almost instantly know +that this flake provides a library for python. The `nix flake show` command +already does something similar to this, by telling the user the full name for +the path, e.g. +``` +└───packages + ├───aarch64-linux + │ └───nixops-ovh: package 'python3.9-nixops-ovh-0.1.0' +``` +But this isn't easily searchable. + +# Examples and Interactions +[examples-and-interactions]: #examples-and-interactions + +Given the following `flake.nix`. +```nix +#flake.nix +{ + description = "Minetest server version 5: Infinite-world block sandbox game"; + + labels = [ "minetest" "server" "game" ]; + + #... +} +``` + +When running `nix flake metadata`, on this flake, it would result in the following: +``` +$ nix flake metadata +Resolved URL: ... +Locked URL: ... +Description: Minetest server version 5: Infinite-world block sandbox game +Labels: minetest, server, game +Path: ... +Revision: ... +``` + +When querying [search.nixos.org](https://search.nixos.org/flakes?) with the +following query, `minetest labels:server`, it will return the `minetest` flake, +that also happens to contain the tag `server`. + +# Drawbacks +[drawbacks]: #drawbacks + +There's a chance that, if this gets implemented in multiple tools, the end-user +won't use it. + +# Alternatives +[alternatives]: #alternatives + +1. Try to parse the `description` attribute + This isn't really scaleable, and the description can sometimes be misleading. + +2. Use the github labels + Assuming every single flake in existence will be on github isn't that good of + an idea. + +# Unresolved questions +[unresolved]: #unresolved-questions + +If this is an useful something for the Nix ecosystem to agree upon? + +# Future work +[future]: #future-work + +Labels should be optional, as mentioned above, so existing software will keep +working the way it works right now. It might be possible to use the labels in the +future to implement feature such as a more advance query for search.nixos.org.