From 9b5f6f60610cfd910a0aff25584b8f8a59664bc3 Mon Sep 17 00:00:00 2001 From: Bryan Honof Date: Fri, 3 Sep 2021 10:08:35 +0200 Subject: [PATCH 1/4] Add RFC 0103 --- rfcs/0103-flake-tags-metadata.md | 150 +++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 rfcs/0103-flake-tags-metadata.md diff --git a/rfcs/0103-flake-tags-metadata.md b/rfcs/0103-flake-tags-metadata.md new file mode 100644 index 000000000..f56347877 --- /dev/null +++ b/rfcs/0103-flake-tags-metadata.md @@ -0,0 +1,150 @@ +--- +feature: Flakes metadata (tags) +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`, tags 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 tags `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 `tags` attribute in a flake should NOT be mandatory, but optional. It is +already possible to add an attribute `tags`, 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`. + +## Tags 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 +tags 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 tags in flakes would serve the same purpose, quickly identifying what a +repository is all about through the use of keywords. + +## Tags 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 tags +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 +tags the user could also search for `minetest tags:server`, which would return +all the flakes that provide the `minetest` package, and also have `server` in +their tags list. + +## Tags 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 tags: `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 tags `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"; + + tags = [ "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 +Tags: minetest, server, game +Path: ... +Revision: ... +``` + +When querying [search.nixos.org](https://search.nixos.org/flakes?) with the +following query, `minetest tags:server`, it will return the `minetest` flake, +that also happens to contain the tag `server`. + +# Drawbacks +[drawbacks]: #drawbacks + +There's a change 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 tags + 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 + +Tags 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 tags in the +future to implement feature such as a more advance query for search.nixos.org. From be7ed8c3308de9ac521bd21c07b6fb582fdac0dc Mon Sep 17 00:00:00 2001 From: Bryan Honof Date: Fri, 3 Sep 2021 10:09:56 +0200 Subject: [PATCH 2/4] Fix typo --- rfcs/0103-flake-tags-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0103-flake-tags-metadata.md b/rfcs/0103-flake-tags-metadata.md index f56347877..488195c8c 100644 --- a/rfcs/0103-flake-tags-metadata.md +++ b/rfcs/0103-flake-tags-metadata.md @@ -124,7 +124,7 @@ that also happens to contain the tag `server`. # Drawbacks [drawbacks]: #drawbacks -There's a change that, if this gets implemented in multiple tools, the end-user +There's a chance that, if this gets implemented in multiple tools, the end-user won't use it. # Alternatives From 07201478d76eb923c96cb2e2afa6d2991f3fc23d Mon Sep 17 00:00:00 2001 From: Bryan Honof Date: Wed, 8 Sep 2021 19:10:42 +0200 Subject: [PATCH 3/4] Replace occurrences of tags with labels --- rfcs/0103-flake-tags-metadata.md | 42 ++++++++++++++++---------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/rfcs/0103-flake-tags-metadata.md b/rfcs/0103-flake-tags-metadata.md index 488195c8c..d3482e898 100644 --- a/rfcs/0103-flake-tags-metadata.md +++ b/rfcs/0103-flake-tags-metadata.md @@ -1,5 +1,5 @@ --- -feature: Flakes metadata (tags) +feature: Flakes metadata (Labels) start-date: 2021-09-02 author: Bryan Honof co-authors: (find a buddy later to help out with the RFC) @@ -20,7 +20,7 @@ indexing/searching. [motivation]: #motivation Just as NixPkgs uses a file structure to categorise software, e.g. -`./pkgs/games/minetest`, tags in a flake could function in the same way. Having +`./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. @@ -30,7 +30,7 @@ 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 tags `plugin` and `nixops`, inside their flake. +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. @@ -38,49 +38,49 @@ interface. # Detailed design [design]: #detailed-design -The `tags` attribute in a flake should NOT be mandatory, but optional. It is -already possible to add an attribute `tags`, that is a list of strings, since +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`. -## Tags as a way to tell what the flake repository is about +## 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 -tags assigned to the repository. Namely: `c-plus-plus`, `package-manager`, +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 tags in flakes would serve the same purpose, quickly identifying what a +Having labels in flakes would serve the same purpose, quickly identifying what a repository is all about through the use of keywords. -## Tags as a way to make looking for flakes easier +## 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 tags +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 -tags the user could also search for `minetest tags:server`, which would return +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 tags list. +their labels list. -## Tags as a way to group related software together +## 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 tags: `python3`, `python37`, `python39`, +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 tags `python`, and `library`, would almost instantly know +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. @@ -100,7 +100,7 @@ Given the following `flake.nix`. { description = "Minetest server version 5: Infinite-world block sandbox game"; - tags = [ "minetest" "server" "game" ]; + labels = [ "minetest" "server" "game" ]; #... } @@ -112,13 +112,13 @@ $ nix flake metadata Resolved URL: ... Locked URL: ... Description: Minetest server version 5: Infinite-world block sandbox game -Tags: minetest, server, game +Labels: minetest, server, game Path: ... Revision: ... ``` When querying [search.nixos.org](https://search.nixos.org/flakes?) with the -following query, `minetest tags:server`, it will return the `minetest` flake, +following query, `minetest labels:server`, it will return the `minetest` flake, that also happens to contain the tag `server`. # Drawbacks @@ -133,7 +133,7 @@ won't use it. 1. Try to parse the `description` attribute This isn't really scaleable, and the description can sometimes be misleading. -2. Use the github tags +2. Use the github labels Assuming every single flake in existence will be on github isn't that good of an idea. @@ -145,6 +145,6 @@ If this is an useful something for the Nix ecosystem to agree upon? # Future work [future]: #future-work -Tags 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 tags in the +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. From 53ad4e46311f7eed2ad91781fd242598f286c1ba Mon Sep 17 00:00:00 2001 From: Bryan Honof Date: Thu, 9 Sep 2021 08:58:02 +0200 Subject: [PATCH 4/4] Rename rfc 0103 --- ...{0103-flake-tags-metadata.md => 0103-flake-labels-metadata.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rfcs/{0103-flake-tags-metadata.md => 0103-flake-labels-metadata.md} (100%) diff --git a/rfcs/0103-flake-tags-metadata.md b/rfcs/0103-flake-labels-metadata.md similarity index 100% rename from rfcs/0103-flake-tags-metadata.md rename to rfcs/0103-flake-labels-metadata.md