search

NixOS / nixpkgs

Nix Packages collection & NixOS
MIT License
16.4k stars 12.9k forks source link

k3s: Documentation Updates #313252

Closed wrmilling closed 5 days ago

wrmilling commented 1 month ago

Problem

The k3s documentation is in need of a refactor due to length and clarity concerns.

Proposal

Rebuild the NixOS Wiki and nixpkgs documentation for the k3s module and packages to be clear and concise. Facilitate through this PR a discussion of any changes to the process of maintaining the package and make overall process clear to contributors and users.

Checklist

Add a :+1: reaction to issues you find important.

wrmilling commented 1 month ago

This spun off of a conversation in #312795 with @superherointj, figured a small issue to track thoughts and conversation around updates would be useful.

CC: @euank @Mic92 @yajo

superherointj commented 1 month ago

Yes, once release happens we should delete all K3s versions that exist in nixos-stable but the latest. And add the aliases warnings (for those versions).

This is one point where I disagree on the process given those branches still receive upstream support, but something we can discuss as part of any documentation update work.

I also don't like we having to rush versions forward and to drop versions too early. For a brief moment we were more relaxed on this, but a NixOS release manager intervened such that we would not have EOL versions by the end of a NixOS release. Most of the existing K3s documentation was born out of that. @euank tried his best to explain the situation to the release manager. And @euank got away with keeping K3s in nixpkgs. Fortunately, recently Jon Ringer & Wegank came to the understanding that we could judge it by ourselves [within certain limits], which makes things easier, and so we are in a middle ground. A sane approach to this. Because honestly we don't have the resources to handle everything perfectly. Nixpkgs doesn't want packages versioned and wants to drop packages ASAP because build resources are limited and there are security considerations like having to handle CVEs, etc. And other philosophical considerations.

What we got now can work. If somebody still needs some earlier version it is possible to reference it in as a new nixpkgs input. But obviously, it is not as convenient as just pointing to the wanted version label.

superherointj commented 1 month ago

The target of this issue should be to move content from Wiki to nixpkgs k3s's README.md, and keep a reference at Wiki for K3s's README.md.

Some things should be a solution instead of a documentation, such as: K3s reset node script. Firewall rules. But that is not required to close this issue. The thinking here is to use Wiki as a user draft for the documentation.

wrmilling commented 1 month ago

Really appreciate the context provided above, I will think a little deeper on the versioning process as it stands before jumping deeper into that area.

The target of this issue should be to move content from Wiki to nixpkgs k3s's README.md, and keep a reference at Wiki for K3s's README.md.

Some things should be a solution instead of a documentation, such as: K3s reset node script. Firewall rules. But that is not required to close this issue. The thinking here is to use Wiki as a user draft for the documentation.

I don't mind owning the first draft on this as I know everyone is busy, looking like I will have some time this coming weekend for work on it. At first blush we could have a primary README that splits out more specific topics where each topic is made as clear and concise as possible. Possibly an examples style directory if we would like more detailed use cases written out (rather than linking to external examples which can link rot). First stab at a possible structure:

README.md focuses on simple layman's terms descriptions, most basic use case (e.g. single node), and high level descriptions for linking out to the more detailed use cases and reference materials. Keep the cognitive burden of each file low and the purpose clear and constrained.

superherointj commented 1 month ago

On the file structure, I think would be best to have a directory for ./docs/ and keep only the README.md at K3s directory. I agree it's important to provide functional examples. Maybe one for Raspberry Pi which is a common use case.

wrmilling commented 1 month ago

Took a first stab at the documentation update in #314395, take a look when y'all can and would love feedback. There were some inconsistencies in stated intent and execution details for package maintenance so I tried to reconcile them so that versioning policy and execution details matched. If I missed the mark for historical conversations, let me know.