This is the first report of the Nix team of maintainers. The team was created in October 2022. The report covers the first six months of our work, with the purpose to reflect on what we did, how it went, and what to do next.
- Drafted a vision statement without conclusion
- Set up a team handbook, establishing a work routine, and a review and decision-making process
- Discussed and prioritised bug reports and issues
- Evaluated the merits and implementation strategies of pull requests
- Discussed open design questions that block work on issues or getting pull requests merged
- Discussed overarching or longer-term technical and procedural issues in the team, the project, and the ecosystem
- Example: stabilising the new CLI
- To a lesser extent, collaboratively reviewed pull requests
In the following we evaluate how well we fulfilled our responsibilities as originally stated in the team announcement. In the meantime we clarified and narrowed down our objectives, and will use the new version in the next report.
- We drafted a vision statement and refrained from proceeding, as there were too many open questions without resolution in sight.
- We did not make any significant progress on a technical roadmap. We began working out a plan for stabilising the new CLI, but will now wait for the outcome of RFC 136.
We discussed, reviewed, and merged multiple interesting PRs in collaboration with their authors, including:
- Support for XDG directories (@balsoft)
- Reading installable paths from
- More context in Nix language error messages (@layus)
- Improved error messages on conflicting profiles (@bobvanderlinden)
- Improved error messages related to trusted users and substituters (@solene)
- Self-contained derivation outputs (@ncfavier)
- Displaying the command documentation on separate pages (@balsoft)
The team’s workflow is by now quite well established, and we dedicated a significant amount of total time to the team’s stated goals. We have a rather predictable workflow, formalised in our team handbook, that proved suitable for reviewing and shepherding small to medium changes and making narrowly-scoped design decisions.
Most of the work was still done by team members themselves though. While we helped multiple authors to make progress on their PRs by answering questions, making design decisions, or helping with more involved technical details, many items got stuck in our pipeline because we still tend to lose track of them due to new topics taking our attention.
Overall, our meeting routine proved a solid basis for steering the project, and our current focus on fixing bugs and improving testing and documentation resulted in notable progress in these areas. At the same time, the synchronous process is a bottleneck, given team members can so far only exercise limited autonomy. This is due to very few explicit values and guidelines expressing team consensus. It is compounded by the lack of a more far-reaching vision that would further ease prioritisation.
We set up a PR template that prompts authors to state motivation and provide context, or add more information depending on the complexity or scope of the change. We have also established a checklist for PRs, but we have yet to follow it routinely. We added link checking to documentation. We helped with merging incremental improvements to the testing situation.
We merged a series of refactorings of Nix store code and added multiple tests.
The unit tests of the store layer core data types have been greatly expanded, and included property tests.
We made many significant improvements to the Nix reference manual:
- Documentation rendering code refactored for improved readability
- Link checking was added
- Multiple additions to the glossary
- Reworked and expanded documentation on operators and paths
- Added many details on various settings
- Provided more details on installation and deinstallation
We have established the goal of improving the release process. To this end we have documented the release process. Releases are not signed by any specific person anymore.
Unfortunately we have had a regression on each release during the team’s operation, highlighting the need for improvements to the test suite.
We publish all meeting notes, complete with links to discussions on every issue and pull request, usually within a week. This is the first report, concerning the past 6 months.
We did not engage with third parties as a team except for responding to a direct – literal – request for comments about a proposal to change the Nix language, and collecting feedback for this report.
Team members individually discussed related issues with various people
Since only the most significant user-facing changes appear in the release notes, here is a more complete list of notable pull requests that we merged in this period. The list is grouped by topic and sorted by time of completion, and gives an impression of how we distributed our efforts.
#7500 Updated docs to delete build users and group
#7607 Expand installation instructions
#7418 Add GitHub template for installer issues
#7547 Fix Nix installation on older versions of fish
#7551 Include macOS sandbox files in the Nix binary
#7411 Remove GPG-signing of releases
#7132 Fix fish shell
requires non-existent output(a non-repeatable failure)
#7725 Disable GC during coroutine execution (Mitigate evaluator GC crash on Darwin)
#7796 Flakes: Ensure that
self.outPath == ./.
#7006 Manual: generalize anchor redirects
#7541 Check links in the manual
#7913 Add information on the
builtins.fetchGitwhen used on a local path
#7318 Add “instantiate” to glossary
#7714 doc: add
#7490 Define the terms “realise” and “valid” for store paths in the glossary
#7628 doc: Update
#7498 Refactor documentation of operators, document
+for strings and paths
#7278 antiquotation → string interpolation
#7066 Manual: architecture overview
#7485 Define “store derivation” in the glossary
#7300 Manual: Add links to GitHub source, set title to “Nix Reference Manual”
#7191 Explain how Nix handles antiquotation of paths
#7594 read installable paths from
#5588 Follow XDG Base Directory standard
#7754 Scope down
--derivationto just the commands that use it
#7474 Use a pipe for all install commands
nix-shell: Colour the prompt red if the user is
#5226 Move the default profiles to the user’s home
nix flake show: don’t evaluate derivations for foreign systems by default
#7087 Self-contained derivation outputs
flake check: Recognize well-known community attributes (
nix develop: Set Linux personality
#7423 Support flake references in the classic CLI
#3600 Automatic UID allocation
#7788 Improve error on conflict for
nix profile install
#7461 Improve warning when an untrusted user is using an untrusted substituter
#6204 Add context to better locate runtime coercions
#7473 Improve SQLite error messages
#7462 Inform user instead of warning them when using a trusted substituter
#7883 Add JSON design guideline
libcmdheaders and files
#6538 Simplify flake for this repository
#7744 Factor out
InstallableStorePathto its own file, deduplicate
.github: Add pull request template
#7412 Document the release process
hacking.mdand add clangd+bear to devshell
#7427 State priorities in triaging and discussion process
#7329 Add maintainers’ handbook
The team’s main responsibility is to set a direction for the development of Nix and ensure that the code is in good shape.
We aim to achieve this by improving the contributor experience and attracting more maintainers – that is, by helping other people contributing to Nix and eventually taking responsibility – in order to scale the development process to match users’ needs.
For the next 6 months period, we aim to orient our activities around achieving the following objectives, against which we will measure our success:
- It is obvious what is worthwhile to work on.
- It is easy to find the right place in the code to make a change.
- It is clear what is expected of a pull request.
- There is a predictable process for getting a change merged and released.
From the above objectives we derive the following tasks to focus on:
- Establish, communicate, and maintain a technical roadmap
- Improve documentation targeted at contributors
- Record architecture and design decisions
- Elaborate contribution guides and abide to them
- Define and assert quality criteria for contributions
- Maintain the issue tracker and triage pull requests
- Help contributors succeed with pull requests that address roadmap milestones
- Manage the release lifecycle
- Regularly publish reports on work done
- Engage with third parties in the interest of the project
- Ensure the required maintainer capacity for all of the above