lib: Document stability guarantee

[infinisil]

Description of changes

Could be better, but this is a good start :)

Prompted by @Janik-Haag, ping @roberth for review

---

This work is sponsored by Antithesis ✨

Add a 👍 reaction to pull requests you find important.

[Janik-Haag]

Uhm, this seems a bit extreme. There will always be some factors causing a little change, sometimes even external ones. I think a better policy would be to avoid breaking changes if possible, but allow them for every new stable release if they are documented and reasoned accordingly.

[pennae]

for example: @infinisil you do realize that this would have made the markdown transition completely impossible, right? "no breaking changes" is a nonsensical policy for anything that isn't capital d Done (and for those things it's not necessary, because they're done.)

(this includes your revised position of "if not released yet".)

[infinisil]

It's very rare that a breaking change is necessary, we haven't had a real one in the past 2 releases (and I didn't write release notes before that):

• 24.05: None at all
• 23.11: Just removal of deprecated functions and a very minor one to lib.foldl' and friends

I think it's fine to say "no breaking changes", but not insist on it when there's a good case for it.

[infinisil]

@pennae I guess I can clarify that removing deprecated functions is fine after some time (but removing functions without deprecating them is not).

[K900]

Then that should be spelled out very clearly in the document, along with a deprecation process. "No API changes ever EVER" is not something we want, and not something we can achieve even if we did want it.

[eclairevoyant]

Sure. I was simply addressing numinit's usecase.

[numinit]

Neat, thanks. Still glad to see the latter case too :-)

[Janik-Haag]

Splitting lib into a separate repository sounds like a bad idea. The "beauty" of nixpkgs is that you can easily do large refactors, bisecting, etc... there is a reason why most similar projects are structured in a monorepo like fashion (we can and should consider doing regular repository exports, maybe with something like josh). What we should imho do is unify the entry points for lib and not make them gaslight you, currently there are like 4 different ones with at least one changing the behavior of lib.evalModules without telling you. But all of this is off-topic and beside the point, providing a longer stability guarantee for lib than we do for modules is ridiculous.

[roberth]

changing the behavior of lib.evalModules without telling you

👀 I think you're referring to the NixOS library nixos/lib, and I'd be guilty of that. We could rename that function there if you think it's confusing. To be clear that library is supposed to be NixOS-as-a-library, and not a clone of Nixpkgs lib.

As for the flake lib, that's definitely a problem. I'd be in favor of moving the Nixpkgs lib to (getFlake "nixpkgs").lib.lib, so that lib.nixos isn't presented as a Nixpkgs lib sublibrary.

What's the other entrypoint?

[Janik-Haag]

👀 I think you're referring to the NixOS library nixos/lib, and I'd be guilty of that. We could rename that function there if you think it's confusing. To be clear that library is supposed to be NixOS-as-a-library, and not a clone of Nixpkgs lib.

Yes I'm and yes I think having different names would make sense here, e.g. lib.evalModules and lib.evalNixOS or something similar. E.g. I was talking with someone about the minimalModules feature flag some time ago, and differentiating between lib/ and nixos/lib was a bit confusing here.

As for the flake lib, that's definitely a problem. I'd be in favor of moving the Nixpkgs lib to (getFlake "nixpkgs").lib.lib, so that lib.nixos isn't presented as a Nixpkgs lib sublibrary.

What's the other entrypoint?

IIRC there is the flake one, the lib/ one, the lib that gets passed to you inside a nixos module and pkgs.lib

infinisil has done a great job at maintaining lib, and he always listens to contributors, so I really don't get why the tone changed.

I want to disagree with this, I know at least one case where people opted to contribute to nixos/lib/ instead of lib/ and multiple cases where people out right started to avoid contributing to nixpkgs because of the dreadful experiences they had trying to contribute to lib/

[eclairevoyant]

Does this mean it needs to be deprecated for 6 calendar months, or that functions can be removed the day after the release it was deprecated in?

[infinisil]

They can be removed immediately following the release branch-off, so that the release will have the warning, while the next one won't, I'll clarify this.

[roberth]

I'd prefer for deprecations to start after old stable EOL, especially if it doesn't have the new alternative. That adds one month, but provides a guarantee that third party libraries work with all currently supported versions of lib, ensuring that maintainers don't get caught in this sequence of events:

• users report deprecation warning
• maintainer acts on it
• users report evaluation error on a supported Nixpkgs release
• frustrated maintainer has to revert or write a workaround

Alternatively, we could require a backporting of the new thing to stable / old stable to mitigate compatibility issues, but that's slightly more effort.

[nixos-discourse]

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

https://discourse.nixos.org/t/discussion-on-type-functor-changes/57282/3