Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal to changes in contribution guidelines for custom nixpkgs #56545



Copy link

@acyuta108 acyuta108 commented Feb 28, 2019

Motivation for this change

I would like to encourage devs contributing to Nixpkgs repositories to add a for any package that requires configuration. I learnt a great deal about Nix and NixOS in the past 2 weeks, since I dove head-first, thanks to the great design of the package manager and the OS, and the discussions and contributions, but in many cases it would be a better user experience, for noobs in Nix or linux, to have a proper documentation page appended to the nix package/derivation in Github.

This definitely applies to packages that require a config file or one that add a systemd service or udev rules.
Now, the nix derivations are not impossible to read, but for a non-Haskell or a new user, it's a bit tough to figure out where (local .nixpkgs/config.nix or /etc/nixos/configuration.nix) and how to structure/setup the configuration. I have seen a few packages have some #configuration block at the bottom of the nix file but it wouldn't take much effort to have a nicely formatted and simple documentation.

I also think this will greatly reduce the learning curve and teach new comers the proper and (hopefully) standardize way to install and setup packages in Nix or NixOS.

Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nox --run "nox-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Assured whether relevant documentation is up to date
  • Fits

Copy link

@nixos-discourse nixos-discourse commented Feb 28, 2019

This pull request has been mentioned on Nix community. There might be relevant details there:

Copy link

@edolstra edolstra commented Mar 1, 2019

👎 on adding undiscoverable READMEs. Using Nixpkgs should not require browsing the Nixpkgs source tree.

Copy link

@dubiouscript dubiouscript commented Mar 1, 2019

-1 on adding undiscoverable READMEs. Using Nixpkgs should not require browsing the Nixpkgs source tree.

this reminded me that while looking in/at the "source tree"
eg directory hierarchy

it seams a shame the effort is made to organize packages ect into this tree
and as you say

Using Nixpkgs should not require browsing the Nixpkgs source tree.

but!! it would be nice (IMHO) for users to be able to discover packages ( or even as this issue suggests documentation ) by navigating a tree
eg to look for games in dir tree @ NixOS/nixpkgs/../pkgs/games

while it makes sense not browsing -THE- source tree , it could be possible to allow browsing -a tree- of package's and or documentation that mirrors the nice directory hierarchy of the Nixpkgs source tree!

at least that is from my point of view !!

Copy link

@acyuta108 acyuta108 commented Mar 1, 2019


-1 on adding undiscoverable READMEs

How is a Github README undiscoverable when it is indexed by [insert your favorite search engine name here]? In my short life (3 weeks) using Nix, I have found 75% of the packages I search/need in Google, linking directly into this Github repo, since the cli (nix-env -qa) does not return (fuzzy) results unless I know the "correct" name of the package. Try searching nix-env -qaP shadowsocks, there is 2 packages but neither one is returned by the cli (nor GH general search unless you "Search this repository"). Google finds them no problem. Maybe there's a way to search meta data (description) through the cli I don't know about?
That's still not address the lack of configuration documentation.

Using Nixpkgs should not require browsing the Nixpkgs source tree.

Indeed, so what is your solution?
I am suggesting one which I am pretty sure is not the canonical/correct one, but it fixes the issue I am addressing, which I strongly believe should be addressed.


This comment has been hidden.

Copy link

@vcunat vcunat commented Mar 1, 2019

What about some attribute? I'm not sure whether to discuss that here or on discourse where I've put more details.

Copy link

@acyuta108 acyuta108 commented Mar 1, 2019

I'm not sure what is so wrong with a README file. Every repo in GH has one. It's searchable (in page and search engine), supports versioning, it has nice formatting and it can be collocated to the actual package, and: it's free and immediately available since there is no extra coding to make it work in search result (unlike
The only downside I see is for devs cloning and updating the repo will have extra data to download and store.

From what I can tell, the only 2 official ways to search Nixpkgs are the cli and If we can modify the web client, then sure, adding a meta.configuration might be useful.

Having said that, I don't think it will improve the UX when you search, since it's going to add extra data to the response, which btw is already somewhat slow (no caching?).

Better to offload the storage and availabilty to GH, don't you think?

Copy link

@acyuta108 acyuta108 commented Mar 11, 2019

Here is a great example of what I think should/could be the standard:
Without those instructions a js/node dev as myself would be fumbling around for hours just trying to install some npm packages.

Copy link

@doronbehar doronbehar commented May 16, 2020

@acyuta108 if you still think this kind of change is needed. File an RFC at . I'm closing as too much time has passed for this PR too ancient.

@doronbehar doronbehar closed this May 16, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

7 participants