Doc missing: Deprecation process

[matthiasbeyer]

Issue description

There are no docs how we deprecate packages and services in nixpkgs.

See: #64009

[infinisil]

Relevant is my previous NixOS/rfcs#33, which I intend to pick up again eventually

[lheckemann]

#43560, an attempt at deprecating packageOverrides, is somewhat related I guess

[stale]

Hello, I'm a bot and I thank you in the name of the community for opening this issue.

To help our human contributors focus on the most-relevant reports, I check up on old issues to see if they're still relevant. This issue has had no activity for 180 days, and so I marked it as stale, but you can rest assured it will never be closed by a non-human.

The community would appreciate your effort in checking if the issue is still valid. If it isn't, please close it.

If the issue persists, and you'd like to remove the stale label, you simply need to leave a comment. Your comment can be as simple as "still important to me". If you'd like it to get more attention, you can ask for help by searching for maintainers and people that previously touched related code and @ mention them in a comment. You can use Git blame or GitHub's web interface on the relevant files to find them.

Lastly, you can always ask for help at our Discourse Forum or at #nixos' IRC channel.

[lheckemann]

still no docs

[stale]

I marked this as stale due to inactivity. → More info

[matthiasbeyer]

.

[davidak]

I documented deprecating packages here: https://github.com/NixOS/nixpkgs/pull/116475/files

There is no documentation for options yet. A bit can be learned from the review requirements: https://nixos.org/manual/nixpkgs/unstable/#reviewing-contributions-module-updates

There is mkRenamedOptionModule and mkRemovedOptionModule with documentation in the code.

nixpkgs/lib/modules.nix

Lines 980 to 1006 in b52821f

	/* Return a module that causes a warning to be shown if the
	specified option is defined. For example,
	mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "<replacement instructions>"
	causes a assertion if the user defines boot.loader.grub.bootDevice.
	replacementInstructions is a string that provides instructions on
	how to achieve the same functionality without the removed option,
	or alternatively a reasoning why the functionality is not needed.
	replacementInstructions SHOULD be provided!
	*/
	mkRemovedOptionModule = optionName: replacementInstructions:
	{ options, ... }:
	{ options = setAttrByPath optionName (mkOption {
	visible = false;
	apply = x: throw "The option `${showOption optionName}' can no longer be used since it's been removed. ${replacementInstructions}";
	});
	config.assertions =
	let opt = getAttrFromPath optionName options; in [{
	assertion = !opt.isDefined;
	message = ''
	The option definition `${showOption optionName}' in ${showFiles opt.files} no longer has any effect; please remove it.
	${replacementInstructions}
	'';
	}];
	};

Here is an example of an option being deprecated: 3485204

[nixos-discourse]

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

https://discourse.nixos.org/t/2022-10-22-documentation-team-meeting-notes-12-nixcon-edition/22689/1