Documentation: list experimental features in manual by peeley · Pull Request #7798 · NixOS/nix

peeley · 2023-02-10T05:14:14Z

Motivation

This PR updatesnix.conf manual page with a list of all current experimental features. Also adds a comment reminding future contributors to update the list of experimental commands in the docs when the list is changed.

Context

Currently, the manual does not list what experimental features are available, and grepping through the source is the most direct method.

See #7368 for more info.

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

agreed on idea
agreed on implementation strategy
tests, as appropriate
- functional tests - tests/**.sh
- unit tests - src/*/tests
- integration tests - tests/nixos/*
documentation in the manual
code and comments are self-explanatory
commit message explains why the change was made
new feature or incompatible change: updated release notes

src/libstore/globals.hh

nixos-discourse · 2023-02-22T01:34:02Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/prs-ready-for-review/3032/1860

nixos-discourse · 2023-03-27T13:43:24Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-03-23-nix-team-meeting-minutes-43/26758/1

Lists all current experimental features in the `nix.conf` manual.

src/libutil/experimental-features.cc

…-features

- Use struct not `std::pair`, designated initializers - Use `constexpr` array that we can index by enum tag - It no longer segfaults; not sure why.

Prior to this, there was an ad-hoc whitelist in `main.cc`. Now, every command states its stability. In a future PR, we will adjust the manual to take advantage of this new information in the JSON. (It will be easier to do that once we have some experimental feature docs to link too; see NixOS#5930 and NixOS#7798.)

src/libutil/experimental-features.cc

fricklerhandwerk

Thanks a lot! This change is a great improvement on many levels:

we finally get an full, automated overview of experimental features
we get more documentation on what they are about
the cross-linking exposes powerful new capabilities to users which would otherwise go unnoticed

Because I think this will have quite some impact, I'd prefer that we take the time to get the added information right. @peeley if implementing my suggestions feels like too much work for you, we can lift this to the @NixOS/documentation-team to get more eyes and hands on it. Would be great if we can move this forward and merge soon.

src/libutil/experimental-features.cc

fricklerhandwerk · 2023-04-04T22:25:19Z

src/libutil/experimental-features.cc

+            derivation attribute to `true`. See [these release
+            notes](../release-notes/rl-2.8.md) for an example.


Please expand that information here. Release notes are not documentation, and it's a good occasion to lift that stuff to where it's visible for users.

src/libutil/experimental-features.cc

Co-authored-by: Valentin Gagarin <[email protected]>

…-features

Instead of constructing a markdown list in C++ (which involved all sorts of nasty string literals), export some JSON and assemble it with the manual build system. Besides following the precedent set with other dumped data, this is a better separate of content and presentation; if we decide for example we want to display this information in a different way, or in a different section of the manual, it will become much easier to do so.

peeley · 2023-04-06T03:21:05Z

Thanks a lot! This change is a great improvement on many levels:

we finally get an full, automated overview of experimental features

we get more documentation on what they are about

the cross-linking exposes powerful new capabilities to users which would otherwise go unnoticed

Because I think this will have quite some impact, I'd prefer that we take the time to get the added information right. @peeley if implementing my suggestions feels like too much work for you, we can lift this to the @NixOS/documentation-team to get more eyes and hands on it. Would be great if we can move this forward and merge soon.

@fricklerhandwerk Thank you for the feedback! I've performed some of the requested revisions. For some of the more inscrutable features like recursive-nix, I may have gone overboard with the verbosity/examples. Please let me know if further revisions are necessary or if the docs could be more terse!

fricklerhandwerk

Thanks a lot, that pushes the whole thing to the next level. Please consider the suggestions, trying to simplify things and keep potential confusion low.

src/libutil/experimental-features.cc

nixos-discourse · 2023-04-06T16:45:45Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-04-06-documentation-team-meeting-notes-39/27048/1

Adds examples and additional information to the `impure-derivations`, `recursive-nix`, and `no-url-literals` experimental feature documentation.

Ericson2314 · 2023-04-06T21:54:35Z

@peeley Sorry we've been half-commandeering your PR, but while we do it would be nice if no one force-pushes to it. We lost the last round of changes I did I believe unintentionally, for example.

src/libutil/experimental-features.cc

Co-authored-by: Valentin Gagarin <[email protected]>

…-features

They are put in the manual separate pages under the new overarching description of experimental features. The settings page just lists the valid experimental feature names (so people know what a valid setting entry looks like), with links to those pages. It doesn't attempt to describe each experimental feature as that is too much information for the configuration settings section.

Ericson2314 · 2023-04-06T22:09:28Z

(I merged master and cherry-picked the lost commits again, so we are all good now.)

peeley · 2023-04-06T22:10:46Z

@Ericson2314 Ah, I'm sorry! Hadn't been keeping my local branch up to date, did not mean to lose history.

Ericson2314 · 2023-04-06T22:14:53Z

All good, these things happen.

@fricklerhandwerk

As requested by @fricklerhandwerk.

src/libutil/config.hh

src/libutil/experimental-features.cc

nixos-discourse · 2023-04-18T13:10:29Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-47/27387/1

nixos-discourse · 2023-05-05T19:54:24Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/this-month-in-nix-docs-2-april-2023/27899/1

peeley requested review from edolstra and thufschmitt as code owners February 10, 2023 05:14

edolstra requested changes Feb 10, 2023

View reviewed changes

src/libstore/globals.hh Outdated Show resolved Hide resolved

peeley force-pushed the list-experimental-features branch from b226aca to 0a04bdb Compare February 18, 2023 02:27

peeley requested review from edolstra and removed request for thufschmitt February 18, 2023 02:28

fricklerhandwerk added the documentation label Feb 28, 2023

thufschmitt assigned edolstra Mar 24, 2023

thufschmitt added the idea approved The given proposal has been discussed and approved by the Nix team. An implementation is welcome. label Mar 24, 2023

github-actions bot removed the documentation label Mar 27, 2023

peeley force-pushed the list-experimental-features branch from f49084a to 0a04bdb Compare March 28, 2023 00:11

Documentation: list experimental features in manual

d1d1ae7

Lists all current experimental features in the `nix.conf` manual.

peeley force-pushed the list-experimental-features branch from 0a04bdb to d1d1ae7 Compare March 28, 2023 00:13

Ericson2314 reviewed Mar 28, 2023

View reviewed changes

src/libutil/experimental-features.cc Outdated Show resolved Hide resolved

Ericson2314 added 3 commits April 2, 2023 16:21

Merge remote-tracking branch 'upstream/master' into list-experimental…

b2c9315

…-features

Rework a few things with the experimental features list

2585bca

- Use struct not `std::pair`, designated initializers - Use `constexpr` array that we can index by enum tag - It no longer segfaults; not sure why.

Add more API docs to experimental-features.hh

32d72b1

Ericson2314 mentioned this pull request Apr 3, 2023

Stuctured command stability #7611

Merged

fricklerhandwerk added the documentation label Apr 3, 2023

fricklerhandwerk self-assigned this Apr 4, 2023

Ericson2314 reviewed Apr 4, 2023

View reviewed changes

src/libutil/experimental-features.cc Outdated Show resolved Hide resolved

fricklerhandwerk mentioned this pull request Apr 4, 2023

Mark experimental configuration settings programmatically #8162

Closed

2 tasks

fricklerhandwerk suggested changes Apr 4, 2023

View reviewed changes

Apply suggestions from code review

bdeefff

Co-authored-by: Valentin Gagarin <[email protected]>

Ericson2314 added 2 commits April 4, 2023 21:34

Merge remote-tracking branch 'upstream/master' into list-experimental…

3f98353

…-features

github-actions bot added the documentation label Apr 5, 2023

fricklerhandwerk reviewed Apr 6, 2023

View reviewed changes

fricklerhandwerk assigned 06kellyjac Apr 6, 2023

Ericson2314 mentioned this pull request Apr 6, 2023

Start cross-referencing experimental features #8174

Merged

8 tasks

peeley force-pushed the list-experimental-features branch from 8a6e354 to c654e0a Compare April 6, 2023 21:50

Expand documentation for experimental-features

8a7790f

Adds examples and additional information to the `impure-derivations`, `recursive-nix`, and `no-url-literals` experimental feature documentation.

peeley force-pushed the list-experimental-features branch from c654e0a to 8a7790f Compare April 6, 2023 21:52

fricklerhandwerk approved these changes Apr 6, 2023

View reviewed changes

src/libutil/experimental-features.cc Outdated Show resolved Hide resolved

peeley and others added 4 commits April 6, 2023 15:02

Fix typo in no-url-literals experimental feature docs

e399cb4

Co-authored-by: Valentin Gagarin <[email protected]>

Merge remote-tracking branch 'upstream/master' into list-experimental…

b7cd87a

…-features

Link the new general documentation on xp features on the setting

6c4049b

Ericson2314 approved these changes Apr 6, 2023

View reviewed changes

Single page for experimental feature descriptions

73eb6a2

As requested by @fricklerhandwerk.

edolstra approved these changes Apr 11, 2023

View reviewed changes

src/libutil/config.hh Outdated Show resolved Hide resolved

src/libutil/config.hh Outdated Show resolved Hide resolved

src/libutil/experimental-features.cc Outdated Show resolved Hide resolved

src/libutil/experimental-features.cc Outdated Show resolved Hide resolved

Nitpicks

deb7f4b

edolstra enabled auto-merge April 11, 2023 09:31

edolstra merged commit 60a1bf0 into NixOS:master Apr 11, 2023

bryanhonof mentioned this pull request Apr 12, 2023

Move documentation for impure derivation #8212

Open

8 tasks

fricklerhandwerk mentioned this pull request Apr 17, 2023

manual: list experimental features #7368

Closed

2 tasks

		derivation attribute to `true`. See [these release
		notes](../release-notes/rl-2.8.md) for an example.

Uh oh!

Conversation

peeley commented Feb 10, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Context

Checklist for maintainers

Uh oh!

Uh oh!

nixos-discourse commented Feb 22, 2023

Uh oh!

nixos-discourse commented Mar 27, 2023

Uh oh!

Uh oh!

Uh oh!

fricklerhandwerk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fricklerhandwerk Apr 4, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

peeley commented Apr 6, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fricklerhandwerk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nixos-discourse commented Apr 6, 2023

Uh oh!

Ericson2314 commented Apr 6, 2023

Uh oh!

Uh oh!

Ericson2314 commented Apr 6, 2023

Uh oh!

peeley commented Apr 6, 2023

Uh oh!

Ericson2314 commented Apr 6, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nixos-discourse commented Apr 18, 2023

Uh oh!

nixos-discourse commented May 5, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

peeley commented Feb 10, 2023 •

edited

Loading

peeley commented Apr 6, 2023 •

edited

Loading