move question about channels to FAQs section #744
Conversation
The wording of that is confusing yeah. But it means to say that because Hydra doesn't build a lot of packages for small channels, it means that users may have to do the builds themselves instead. |
|
There's some duplication here with https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#flow-of-merged-pull-requests, and https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#branch-conventions would be good to link to. |
Deploy Preview
|
There was a problem hiding this comment.
Would you be willing to add more detail on recommendations for how the different channels should be used? If you feel like that's a separate PR that would also be fine. What a new user will get from reading this as it stands is some idea of how the channels are "made", but I think they'll still be missing some idea of which channels they should use in which situations or when they have certain priorities.
Something else that would really help is some kind of diagram. There's a lot of "commits from X end up in Y, and commits from A are backported to B", which is hard to follow textually.
source/concepts/faq.md
Outdated
| Nix channels are reified as git branches in the [nixpkgs](https://github.com/NixOS/nixpkgs) repository. These branches have a relationship to channels, but that relationship is not always 1:1. In general: | ||
|
|
||
| - The main development branch, `master`, is used as the starting point for other unstable channels. | ||
| - `nix(os|pkgs)-unstable` are based on the `master` branch and contain rolling updates for both NixOS|Nix-as-a-Package-Manager (NaaPM). |
There was a problem hiding this comment.
Let's not introduce NaaPM as a new term. You also don't use it again in the document so there's little need to have an abbreviation.
There was a problem hiding this comment.
I think nix(os|pkgs)-unstable reads awkwardly for those who aren't familiar with what | implies.
| - `nix(os|pkgs)-unstable` are based on the `master` branch and contain rolling updates for both NixOS|Nix-as-a-Package-Manager (NaaPM). | |
| - `nixos-unstable` and `nixpkgs-unstable` are based on the `master` branch and contains rolling updates for both NixOS and nixpkgs. |
Edit: OTOH, https://github.com/NixOS/nix.dev/pull/744/files#r1368791182 is the way to go IMO. As this information information is more helpful for nixpkgs maintainers/contributors.
source/concepts/faq.md
Outdated
| - The main development branch, `master`, is used as the starting point for other unstable channels. | ||
| - `nix(os|pkgs)-unstable` are based on the `master` branch and contain rolling updates for both NixOS|Nix-as-a-Package-Manager (NaaPM). | ||
| - `release-YY.MM` branches are used for stable channels as merge targets for backports. | ||
| - Branches like `nixos-YY.MM` or `nixpkgs-YY.MM` point to a successful commit from the corresponding `release-YY.MM` branch. Used for stable channels. |
There was a problem hiding this comment.
This one is a little confusing, it makes it sound like these are just tags rather than branches.
source/concepts/faq.md
Outdated
| - `nix(os|pkgs)-unstable` are based on the `master` branch and contain rolling updates for both NixOS|Nix-as-a-Package-Manager (NaaPM). | ||
| - `release-YY.MM` branches are used for stable channels as merge targets for backports. | ||
| - Branches like `nixos-YY.MM` or `nixpkgs-YY.MM` point to a successful commit from the corresponding `release-YY.MM` branch. Used for stable channels. | ||
| - `staging` and `staging-YY.MM` are used for mass rebuilds (number of rebuilds > 500) of the `master` and the `release-YY.MM` branches respectively. |
There was a problem hiding this comment.
These branches also contain the latest versions of packages that are known to build, correct?
Hi @zmitchell. Of course! How about adding a couple of recommendations at the end of each channel's definition?
I definitely agree, an image goes a long way. But looking at different sources (see for example: Python FAQs or Haskell FAQs, FAQs seem to consist of one or two paragraphs, links and maybe a block of code. How about if we reference this diagram to explain the different commits in the different branches? And update that diagram (if necessary) instead? |
|
I feel the answer to this question comes across already as too verbose/wordy and would like to propose to split it into two: one for the channels and one for the branches. What do you think? |
|
This looks a lot like duplicating Nixpkgs documentation to me. @wamirez if you found anything new about branches that's not in the Nixpkgs contributor documentation (or feel like rewording that for clarity and brevity would help), please PR against that. Then it will be enough to say in this FAQ answer that there is a distinction between branches and channels, and point to reference docs for each. IIRC there is no explicit documentation on channels yet, so it would make sense to merge that here and move it if we find a better place later. If I'm wrong and there is some already, use the same procedure as above. |
|
Btw I broke the GitHub markdown anchors in the past by changing the section titles, but it should be possible to maintain them into the future using extra backwards compatibility anchors. Since these docs are in git though, we can also just link to the anchor from a specific commit, which will definitely not break. |
|
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 |
|
Last commit is kind of a condensed summary of everyone's suggestions/observations here and of information found on Document channel branches and release channels · Issue #263230 · NixOS/nixpkgs · GitHub |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-11-02-documentation-team-meeting-notes-91/34938/1 |
fricklerhandwerk
dismissed
zmitchell’s stale review
implemented all suggestions
Co-authored-by: Alexander Groleau <alex@proof.construction> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> Co-authored-by: Silvan Mosberger <silvan.mosberger@tweag.io>
|
@wamirez excellent collaboration, thank you very much for your patience. You really unearthed a nasty issue here. |
| ### Stable | ||
|
|
||
| - On Linux (including NixOS and WSL), use [`nixos-*`](https://github.com/NixOS/nixpkgs/branches/all?query=nixos-). | ||
|
|
||
| These branches only contain commits that passed the NixOS test suite. | ||
| - On any other platform, use [`nixpkgs-*`](https://github.com/NixOS/nixpkgs/branches/all?query=nixpkgs-). | ||
|
|
||
| These branches contain commits that passed the test suites specific to other platforms. |
There was a problem hiding this comment.
I really don't think this is right, as mentioned before. The only stable nixpkgs-* channels are the Darwin ones like nixpkgs-23.05-darwin, but we cannot assume that all non-Linux platforms must be Darwin, or that the darwin jobsets will run tests on those platforms. This is just confusing like this.
As mentioned in #744 (comment)
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-11-06-documentation-team-meeting-notes-92/35243/1 |
As mentioned in #744 (comment) Later refined in #791 (comment)
Moved:
from recipes/faq.md to concepts/faq.md.
However, there's way too many asumptions being made I can't just yet understand/prove. One example off the top of my fingers: "Small channels (...) update faster, but require in turn more packages to be built from source.", when comparing small channels to large ones. The update part I get, the second part, I don't.
A thorough review is needed, especially for the branch part. Also, should this branch part be a question on his own?
The answer for this question is built from the following sources:
Channels' sources:
Branches' sources: