!UNVBThoJtlIiVwiDjU:nixos.org

Staging

389 Members
Staging merges | Running staging cycles: https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+head%3Astaging-next+head%3Astaging-next-25.11 | Review Reports: https://malob.github.io/nix-review-tools-reports/125 Servers

Load older messages

SenderMessageTime
28 Jun 2026
@emilazy:matrix.orgemilybut yeah it's pretty confusing21:16:21
@hexa:lossy.networkhexaI think it's just a lot to take in21:21:49
@emilazy:matrix.orgemilyyeah, the ideal would be presenting the high-level principles and most important requirements upfront in a screen or two of text, with links to more detail21:25:56
@grimmauld:m.grimmauld.deGrimmauld (any/all)The people with whom i talked about starting out contributing mostly were willing to learn/read a lot, just intimidated by the amount of shit we have, scared to overlook something. Which, admittedly, it is quite easy to overlook something. When i review things, i try not to waste my or the reviewees time. Our documentation is currently NOT structured in a way that attempts to not waste time. Its dumped in random places, and even just getting an overview is a significant investment we expect new contributors to do. I don't think this is idea.21:26:22
@grimmauld:m.grimmauld.deGrimmauld (any/all)* The people with whom i talked about starting out contributing mostly were willing to learn/read a lot, just intimidated by the amount of shit we have, scared to overlook something. Which, admittedly, it is quite easy to overlook something. When i review things, i try not to waste my or the reviewees time. Our documentation is currently NOT structured in a way that attempts to not waste time. Its dumped in random places, and even just getting an overview is a significant investment we expect new contributors to do. I don't think this is ideal.21:26:26
@emilazy:matrix.orgemilycan't avoid writing down specifics, but right now you have to wade through lots of tl;dr detail just to learn all the basic expectations about patching, commit messages etc.21:26:34
@grimmauld:m.grimmauld.deGrimmauld (any/all) And even then its a mess. I think we still don't have consensus about the fetchpatch2 situation... 21:27:53
@opandddd:matrix.orgSapii/Sapersonmaybe these can be moved up in the contrib.md so its the first thing seen? 21:28:22
@emilazy:matrix.orgemilyI think it's more like even with consensus we don't have people putting the effort into fixing things21:28:33
@grimmauld:m.grimmauld.deGrimmauld (any/all) if documentation were all in files, that'd be one thing. But sending newbies to years-ongoing technical discussions is bad 21:28:33
@emilazy:matrix.orgemilymyself included, it's just a rabbit hole I don't have time for21:28:45
@emilazy:matrix.orgemilyand nobody owns our contributing docs really21:28:52
@grimmauld:m.grimmauld.deGrimmauld (any/all)sure21:29:01
@emilazy:matrix.orgemilyit would be very high-value work if people wanted to improve them21:29:18
@grimmauld:m.grimmauld.deGrimmauld (any/all)everyones workflow is different. I have ideas how i would want contributing docs to be structured, but collecting all the things that need to be documented is tedious and making it work for everyone is basically impossible21:30:37
@emilazy:matrix.orgemilywell, right now they work for nobody :)21:32:39
@grimmauld:m.grimmauld.deGrimmauld (any/all) I'd want:

  1. a directory of contributing docs

  2. markdown, same format as our other docs

  3. nix code blocks are syntax-checked

- bonus point if nix code blocks are reasonably easy to eval in a repl to poke somehow

  1. one file per common pattern, potentially with examples

  2. a list of useful tools and when to use them

- git-merge-base master staging
- tell people to STOP WASTING COMPUTE with nixpkgs-review without thinking
- tell people to think? XD

  1. explicitly document what we expect from

- a new contributor
- a new package/module
- exiting packages/modules
- existing contributors/committers
- how to do (good) reviews that are useful, even if the reviewer is not a committer
- includes security considerations

  1. where/how to find

- help
- examples
- "inspiration" from how other distros do things (and how that translates to nix)< 		21:37:37
@grimmauld:m.grimmauld.deGrimmauld (any/all) I'd want:

  1. a directory of contributing docs

  2. markdown, same format as our other docs

  3. nix code blocks are syntax-checked

- bonus point if nix code blocks are reasonably easy to eval in a repl to poke somehow

  1. one file per common pattern, potentially with examples

  2. a list of useful tools and when to use them

- git-merge-base master staging
- tell people to STOP WASTING COMPUTE with nixpkgs-review without thinking
- tell people to think? XD

  1. explicitly document what we expect from

- a new contributor
- a new package/module
- exiting packages/modules
- existing contributors/committers
- how to do (good) reviews that are useful, even if the reviewer is not a committer
- includes security considerations

  1. where/how to find

- help
- examples
- "inspiration" from how other distros do things (and how that translates to nix)

  1. a proper style guide

21:37:56
@grimmauld:m.grimmauld.deGrimmauld (any/all)okay formatting got butchered in my matrix client....21:38:08
@grimmauld:m.grimmauld.deGrimmauld (any/all) I'd want:
-  a directory of contributing docs
-  markdown, same format as our other docs
-  nix code blocks  are syntax-checked
  - bonus point if nix code blocks are reasonably easy to eval in a repl to poke somehow
-  one file per common pattern, potentially with examples
-  a list of useful tools *and when to use them*
  - `git-merge-base master staging`
  - tell people to STOP WASTING COMPUTE with `nixpkgs-review` without thinking
  - tell people to think? XD
-  explicitly document what we expect from
  - a new contributor
  - a new package/module
  - exiting packages/modules
  - existing contributors/committers
  - how to do (good) reviews that are useful, even if the reviewer is not a committer
  - includes security considerations
-  where/how to find
  - help
  - examples
  - "inspiration" from how other distros do things (and how that translates to nix)
-  a proper style guide
21:38:19
@grimmauld:m.grimmauld.deGrimmauld (any/all)ther,e thats a bit less awful+21:38:34
@grimmauld:m.grimmauld.deGrimmauld (any/all)* there, thats a bit less awful21:38:39
@emilazy:matrix.orgemilyI somewhat like having the contributor docs "right there" on GitHub in a way but I also feel like it might be more discoverable if we just had a "Nixpkgs contributors manual" alongside the others21:38:58
@emilazy:matrix.orgemilyI get the sense that people are often surprised that we have a bunch of relevant docs that don't appear in the manuals at all21:39:09
@grimmauld:m.grimmauld.deGrimmauld (any/all) manual is just markdown anyways 21:39:15
@grimmauld:m.grimmauld.deGrimmauld (any/all)it'd be in github, in some sense21:39:22
@emilazy:matrix.orgemilyI think these ideas are good, I honestly think the top challenge is just organizing things hierarchically in a way that's useful. you ideally want a top-level document that covers "if you only have 5 minutes to read things, here are the most important things to know", and then you can drill down from there to "if you only have 10 minutes to read about this specific task, …" and so on21:40:41
@grimmauld:m.grimmauld.deGrimmauld (any/all) I'd want:
-  a directory of contributing docs
-  markdown, same format as our other docs
-  nix code blocks  are syntax-checked
  - bonus point if nix code blocks are reasonably easy to eval in a repl to poke somehow
-  one file per common pattern, potentially with examples
-  a list of useful tools *and when to use them*
  - `git-merge-base master staging`
  - tell people to STOP WASTING COMPUTE with `nixpkgs-review` without thinking
  - tell people to think? XD
- common workflows
  - staging
  - backport
  - bot update
  - bot merge
  - channel bumps?
-  explicitly document what we expect from
  - a new contributor
  - a new package/module
  - exiting packages/modules
  - existing contributors/committers
  - how to do (good) reviews that are useful, even if the reviewer is not a committer
  - includes security considerations
-  where/how to find
  - help
  - examples
  - "inspiration" from how other distros do things (and how that translates to nix)
-  a proper style guide
21:40:53
@emilazy:matrix.orgemilydelivering the core principles upfront and then getting into rules-lawyering further down21:41:01
@grimmauld:m.grimmauld.deGrimmauld (any/all)i suspect if i start working on something like this, i'll just end up strongly suggesting my own preferences to everyone XD21:42:05

Show newer messages

Back to Room ListRoom Version: 6