Problem
The Contributing section should not be rendered in the Nixpkgs manual, because it's not something users of Nixpkgs need to know. Only Nixpkgs developers need to know that, and developers can read Markdown files in the source code directly or see them rendered on GitHub.
Compared to user-facing documentation, contributing documentation is closely tied to the source code. This gets especially annoying once we try to expand the contributing documentation to explain how to contribute to more specific parts of Nixpkgs, because we don't want to create a separate section for each part of the source code.
This is motivated by the new draft file structure documentation which talks about various directories and files in Nixpkgs. We should create README's in these directories that explain them in more detail (which I did for lib in #244044), but it's awkward then because why is only the general overview rendered and not the individual parts.
Also, the rendered manual progresses with releases and channel updates, which makes sense for users, but contributors shouldn't orient themselves on those, because they might be outdated. Instead contributors should always look at the latest state of the main branch.
Proposal
- Move the contents of the Contributing section into fitting Markdown files linked to from the root README.md file in Nixpkgs
- Replace the Contributing section with a link to where the table of contents has been moved.
Problem
The Contributing section should not be rendered in the Nixpkgs manual, because it's not something users of Nixpkgs need to know. Only Nixpkgs developers need to know that, and developers can read Markdown files in the source code directly or see them rendered on GitHub.
Compared to user-facing documentation, contributing documentation is closely tied to the source code. This gets especially annoying once we try to expand the contributing documentation to explain how to contribute to more specific parts of Nixpkgs, because we don't want to create a separate section for each part of the source code.
This is motivated by the new draft file structure documentation which talks about various directories and files in Nixpkgs. We should create README's in these directories that explain them in more detail (which I did for
libin #244044), but it's awkward then because why is only the general overview rendered and not the individual parts.Also, the rendered manual progresses with releases and channel updates, which makes sense for users, but contributors shouldn't orient themselves on those, because they might be outdated. Instead contributors should always look at the latest state of the main branch.
Proposal