remove Basic Package Management section

[fricklerhandwerk]

Motivation

this is the first thing most beginners see, and it misleads them into
assuming nix-env is appropriate for doing anything but setting and
reverting profile generations.

this chapter is the root of most evil around the ecosystem, and today we
finally close it for good.

Context

the corner stone of #7769

discussed here at length:
https://discourse.nixos.org/t/depreciate-the-use-of-nix-env-to-install-packages/20139

@domenkozar @Ericson2314 @ianthehenry @ners @rapenne-s

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

Priorities

Add 👍 to pull requests you find important.

[bjornfor]

What's the alternative to nix-env? (Experimental commands shouldn't be part of the answer here.)

[edolstra]

I fundamentally disagree with the premise of this PR. nix-env is not a bug or misfeature. The ability to install and upgrade packages independently is the original use case for Nix and still just as valid today.

There is also the UX issue that installing via the command line is a lot easier than having to edit a configuration file and deal with a complex language and syntax errors.

[Ericson2314]

I think we can still side-step whether or not nix-env is good or bad by saying this is tutorial not reference material that is better off living elsewhere.

[NobbZ]

I agree that for some users imperative package management is the way to go, and I do not want to discuss the reasons here. That is not on topic.

Though I want to use this stage to say, why I still do not want to use nix-env to manage them, but would prefer a tool that replaces nix-env --install, --uninstall, and --upgrade.

1. --install installs "random" programs if derivations share the same "name"
2. --install -A can fix this, but
3. --uninstall requires the "name", and not what I told --install -A to use, this causes confusion
4. --upgrades behaviour is unintuitive for a lot of people:
   1. "packages" that have no version bump are left alone, as their dependencies are as well, causing potential issues with old vulnerable SSL versions still being used by a tool that hasn't received a bump in the last couple of years
   2. "packages" that appear in multiple versions within nixpkgs might be randomly upgraded to the latest version available, despite the user asking for a specific major version
5. Some "packages" do just not work after a nix-env -i, as they require additional, deep setup, like 32bit drivers for steam, or putting desktop or unit files in place such that they can be found by application drawers or systemd respectively.

So we really need an imperative tool, which works much more like users expect but at the same time actually uses channels…

Which also puts files in place where they are needed (and cleans them up eventually), or simply tells users when a package is not suitable for being installed by this means (eg. linux kernel).

I am aware that nix profile does exist, though:

• it only tackles some of the issues, not all
• it is not compatible with nix-env as a low level tool at all
• it is experimental

And I am pretty sure that nix profile could be made compatible, if it wasn't replacing profile management but instead augmenting it…

[fricklerhandwerk]

@NobbZ I agree on all points and yet this is somewhat unrelated to this particular issue. My agenda here is to essentially state:

look, we know everyone wants an imperative interface to declarative configurations, but we don't have a good one, sorry. use Nix how we know it to work well until further notice

The main motivation behind this particular set of changes is to avoid the impression that going down a path that leads to confusion is somehow encouraged.

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-03-31-nix-team-meeting-minutes-45/27002/1

[roberth]

Arguably combining arbitrary versions of packages in a mutable manner requires more expertise and intimate knowledge about the packages involved than using an atomic configuration management tool such as NixOS or home-manager. So "basic" sets the wrong expectations.

Can we at least rename this to Mutable Package Management or Imperative Package Management?

[fricklerhandwerk]

Can we at least rename this to Mutable Package Management or Imperative Package Management?

We could, but then we'd have to introduce the counterpart to that, which is not the responsibility of this manual to begin with. I'd rather dissolve those narrative pages into reference documentation and then focus on making the UI self-explanatory such that, once we have that, any user-facing introduction can be very brief.

[Ericson2314]

I think we could rename and then remove.

We could, but then we'd have to introduce the counterpart to that, which is not the responsibility of this manual to begin with.

The rename can also help justify why it belongs on nix.env too.

[fricklerhandwerk]

I think we could rename and then remove.

How would that additional motion help?

What I could do is go over the nix-env --install page and make sure it's useful enough on its own. If people are looking for installing things, they will find that page and then figure out what to do and what to expect.

[roberth]

nix-env still has its own documentation.

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-10-23-documentation-team-meeting-notes-88/34562/1