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

Open
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
6 participants
@acyuta108
Copy link

commented Feb 28, 2019

Motivation for this change

I would like to encourage devs contributing to Nixpkgs repositories to add a README.md 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 CONTRIBUTING.md.

@nixos-discourse

This comment has been minimized.

Copy link

commented Feb 28, 2019

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

https://discourse.nixos.org/t/documentation-for-configuring-nixpkgs/2268/1

@edolstra

This comment has been minimized.

Copy link
Member

commented Mar 1, 2019

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

@dubiouscript

This comment has been minimized.

Copy link

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 !!

@acyuta108

This comment has been minimized.

Copy link
Author

commented Mar 1, 2019

@edolstra

-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.

@nixos-discourse

This comment was marked as outdated.

Copy link

commented Mar 1, 2019

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

https://discourse.nixos.org/t/documentation-for-configuring-nixpkgs/2268/3

@vcunat

This comment has been minimized.

Copy link
Member

commented Mar 1, 2019

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

@acyuta108

This comment has been minimized.

Copy link
Author

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 meta.foo).
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 https://nixos.org/nixos/packages.html. 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?

@acyuta108

This comment has been minimized.

Copy link
Author

commented Mar 11, 2019

Here is a great example of what I think should/could be the standard: https://github.com/NixOS/nixpkgs/blob/master/doc/languages-frameworks/node.section.md
Without those instructions a js/node dev as myself would be fumbling around for hours just trying to install some npm packages.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.