# Move component bound guides from `nix.dev` to `nixpkgs/doc/`

[hsjobeki]

See #1246

Component bound guides should live with their implementation

Reminder:

• NixOS manual (nixpkgs/nixos/doc/manual/) = documentation for the NixOS Linux distribution.
• nixpkgs manual (nixpkgs/doc/) = documentation for the package collection, module system, build helpers, and tooling.

This migration targets the nixpkgs manual.

For NixOS migration a seperate tracking issue will be created:

Move to nixpkgs

recipes/sharing-dependencies.md

Describes how to set up development environments.

Rationale: Uses inputsFrom, mkShellNoCC, mkShell. The canonical pattern for dev shells alongside package builds. Usage instructions in nixpkgs got changed recently to use packages instead of buildInputs

recipes/dependency-management.md

Describes how to set up general projects and how to pin nixpkgs itself.

Rationale: npins for pinning nixpkgs revisions.

Nixpkgs should describe how to use it.

recipes/python-environment.md

merge into nixpkgs/doc/languages-frameworks/python.section.md
That section already exists and is quite lengthy with dupliction between this guide and the nixpkgs manual.

Rationale: Already exists as a section. This guide demonstrates python.withPackages from nixpkgs. Ecosystem-specific but nixpkgs-authored content. Gets out of sync if python.withPackages changes. Maintainers are not aware this pattern is encouraged here.

Retire from nix.dev:

recipes/direnv.md, fold into sharing-dependencies.md

Rationale: Third-party tool guide. "with direnv" pattern is a tiny oneline-add to the dev-shell guide.

Content that already exists in nixpkgs manual

These topics are already covered by the nixpkgs manual. The nix.dev version is either redundant or a guide wrapper around manual content.

nix.dev file	nixpkgs manual file	Notes
tutorials/cross-compilation.md	stdenv/cross-compilation.chapter.md	nixpkgs cross-comp chapter explicitly says "For a hands-on tutorial, see the cross-compilation guide on nix.dev"
tutorials/packaging-existing-software.md	stdenv/stdenv.chapter.md	Same concepts: mkDerivation, phases, pname/version, fetchzip, fetchFromGitHub. nixpkgs is a reference, nix.dev is learn-by-doing, but content substantially overlaps
tutorials/module-system/index.md	module-system/module-system.chapter.md	nixpkgs module-system chapter explicitly links to nix.dev as its introduction
tutorials/module-system/deep-dive.md	module-system/module-system.chapter.md	Same relationship
tutorials/module-system/a-basic-module/index.md	module-system/module-system.chapter.md	Same relationship

Partial overlap

These touch nixpkgs topics but the manual doesn't contain an equivalent guided walkthrough. The nix.dev content adds value that the manual doesn't currently provide.

nix.dev file	nixpkgs manual file	Gap
tutorials/callpackage.md	using/overlays.chapter.md, stdenv/stdenv.chapter.md	callPackage referenced throughout, no standalone tutorial
tutorials/working-with-local-files.md	lib functions reference	lib.fileset in function library, no guided walkthrough
tutorials/first-steps/towards-reproducibility-pinning-nixpkgs.md	using/configuration.chapter.md	Pinning mentioned but no guide
tutorials/first-steps/declarative-shell.md	build-helpers/special/mkshell.section.md	mkShellNoCC documented, not taught as a tutorial
tutorials/first-steps/ad-hoc-shell-environments.md	build-helpers/dev-shell-tools.chapter.md	nix-shell -p referenced, no guide
guides/recipes/sharing-dependencies.md	build-helpers/special/mkshell.section.md	mkShell documented, inputsFrom pattern not
guides/recipes/dependency-management.md	using/configuration.chapter.md	npins not covered in nixpkgs doc
guides/recipes/python-environment.md	languages-frameworks/python.section.md	Python section exists, no guide
reference/pinning-nixpkgs.md	using/configuration.chapter.md	Related to config chapter, pinning approaches overlap
concepts/flakes.md	build-helpers/fetchers.chapter.md	Flakes referenced throughout nixpkgs doc

[fricklerhandwerk]

I think dependency management is sufficiently independent from Nix, Nixpkgs, and NixOS that it should probably stay here. In particular because there are multiple third-party tools involved that allow managing work with the three above.