No content was changed, new titles are wrapped with () to signal that
they will need to be decided on in a future commit.
Section in the manual have been preserved with a simple redirect to
GitHub, the proper anchors should be filled out in a future commit once
the new section names are decided.
This reverts commit 7e6c518ce4.
I misinterpreted Github's CI failure in the notification tab and
thought that I had broken CI on origin/master, so I panic-reverted
before I merged it (I thought they had).
On closer inspection, it appears that the CI failure was not from
the tip that I merged. This PR resubmits the reverted change. I'll
wait for OfBorg to finish this time.
The manual does an okay job of explaining the rules for each of the
three development branches, but really doesn't give any intuition as
to why there are three (why not four? or two?) or how we got where
we are today.
This commit attempts to fix that, by explaining that there is one
branch that allows mass-rebuild commits, and it has a fast-building
branch both upstream and downstream of it (from the perspective of
automated merges).
I have also removed the term "stabilization" from the arc labels.
This vague term is not defined anywhere, and does communicate any
useful information without a longer explanation. Therefore it is
not appropriate for use in a diagram.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
also updates nixdoc to 2.3.0. the nixdoc update is not a separate commit
because that would leave the manual build broken for one commit,
potentially breaking bisects and rebases.
without stable ids on headings we cannot generate stable links to these
headings. nrd complains about this, but the current docbook workflow
does not.
a few generated ids remain, mostly in examples and footnotes. most of
the examples are generated by nixdoc (which has since gained MD export
functions, and the MD export does generate IDs).
The nixpkgs manual contains references to both sri hash and explicit
sha256 attributes. This is at best confusing to new users. Since the
final destination is exclusive use of sri hashes, see nixos/rfcs#131,
might as well push new users in that direction gently.
Notable exceptions to sri hash support are builtins.fetchTarball,
cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and
fetchCrate. None, other than builtins.fetchTarball, are fundamentally
incompatible, but all currently accept explicit sha256 attributes as
input. Because adding backwards compatibility is out of scope for this
change, they have been left intact, but migration to sri format has been
made for any using old hash formats.
All hashes have been manually tested to be accurate, and updates were
only made for missing upstream artefacts or bugs.
The documentation for this diagram explains that the blue arrows are
automatic processes which happen every six hours. There is no
explanation about how the purple arrows happen or how often.
As a new contributor to nixpkgs, I incorrectly assumed that the purple
arrows were also automatic processes (they aren't), which left me sort
of confused about what the whole scheme was accomplishing.
Recently I went through the github history to see how often these
events happen, and realized that the purple arrows are (a) triggered
manually by a nixpkgs project member and (b) happen much, much, much
less frequently than every six hours.
Now everything makes a lot more sense. I suggest the wording change
in this commit, or something similar, to save future contributors the
same confusion that I experienced.
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.
Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist
While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.
To me, as a native English speaker, this doesn't change the meaning of
the sentence at all. But to a non-native speaker, this can read like
the staging-next rules are only recommendations. Let's make this
clearer.
Specify that the merges from master to staging-next to staging are
performed by GitHub actions. This helps the reader understand the
relationship between the branches.
