Nixpkgs/Contributing: Difference between revisions

← Older edit
VisualWikitext
imported>Milahu
+ Run tests locally
Klinger (talk | contribs)
trusted
709 edits
No edit summary
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Contributing ==
Development in NixOS primarily driven by the work in [https://github.com/nixos/nixpkgs nixpkgs on GitHub]. This repository contains both all packages available in your NixOS channel and all the options you can use for configuring your system with your <code>configuration.nix</code>. To get your text editor to recognize Nix expressions, consider installing a Nix [[Editor Modes for Nix Files]].
Development in NixOS primarily driven by the work in [https://github.com/nixos/nixpkgs nixpkgs on GitHub]. This repository contains both all packages available in your NixOS channel and all the options you can use for configuring your system with your <code>configuration.nix</code>. To get your text editor to recognize Nix expressions, consider installing a Nix [[Editor Modes for Nix Files]].


=== Report issues ===
== Report issues ==


Any issue can be reported in the [https://github.com/nixos/nixpkgs/issues nixpkgs issue tracker] on GitHub. Keep in mind that all work on nixpkgs is being done by volunteers and you cannot expect a quick response and solution for all problems you may face. In general Pull Requests have a much shorter round-trip-time.
Any issue can be reported in the [https://github.com/nixos/nixpkgs/issues nixpkgs issue tracker] on GitHub. Keep in mind that all work on nixpkgs is being done by volunteers and you cannot expect a quick response and solution for all problems you may face. In general Pull Requests have a much shorter round-trip-time.


=== Create pull requests ===
== Create pull requests ==
 
If you want to see your package being provided by a channel, creating an issue will most likely not enough. It is up to you to create a [[Contributing to Nixpkgs|nix package description]] in Nixpkgs and create a pull request in the Nixpkgs repository. Pull requests are a way to tell a GitHub project that you've created some changes, which maintainers can easily review, comment on and, and finally merge into the repository.
 
Here's how to create a pull request on GitHub:


==== Fork Nixpkgs on Github ====
If you want to see your package being provided by a channel, creating an issue will most likely not enough. It is up to you to create a nix package description in Nixpkgs and create a pull request in the Nixpkgs repository. Pull requests are a way to tell a GitHub project that you've created some changes, which maintainers can easily review, comment on and, and finally merge into the repository.


Create a GitHub account and fork the [https://github.com/NixOS/nixpkgs nixpkgs repository].  
See [https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#how-to-create-pull-requests How to create pull requests] in nixpkgs CONTRIBUTING.md.
 
==== Add a remote ====
 
On your host, create a new remote location:
<syntaxhighlight lang="bash">
# add your github clone as remote location:
YOUR_GITHUB_NAME=fill-in
git remote add $YOUR_GITHUB_NAME git@github.com:$YOUR_GITHUB_NAME/nixpkgs.git
</syntaxhighlight>


==== Hack Nixpkgs ====
=== Hack Nixpkgs ===


Make any modifications you want to your local copy of the repository, then build the package from the root of the <code>nixpkgs</code> directory with: <syntaxhighlight lang="bash">nix-build -A $yourpackage</syntaxhighlight>
Make any modifications you want to your local copy of the repository, then build the package from the root of the <code>nixpkgs</code> directory with: <syntaxhighlight lang="bash">nix-build -A $yourpackage</syntaxhighlight>
Line 38: Line 23:
</syntaxhighlight>
</syntaxhighlight>


==== Commit your change locally ====
=== Run tests locally ===
 
Commit your change to your local clone of the repository:
<syntaxhighlight lang="bash">
git add FILE_LIST # use git add --patch as needed
git commit
 
==== Check status ====
 
Verify everything is ok - no unexpected dangling files git does not know about yet:
git status
</syntaxhighlight>
 
==== Run tests locally ====


Pushing commits to Github will run tests on Github.<br>
Pushing commits to Github will run tests on Github.<br>
Line 77: Line 49:
* [https://github.com/NixOS/ofborg#how-does-ofborg-call-nix-build ofborg-eval] will call <code>nix-build -A $yourpackage</code>
* [https://github.com/NixOS/ofborg#how-does-ofborg-call-nix-build ofborg-eval] will call <code>nix-build -A $yourpackage</code>


==== Push to your remote repository ====
==== Called without required argument ====
 
This error is produced by <code>nixpkgs-basic-release-checks</code> (Basic evaluation checks)
 
<pre>
anonymous function at /path/to/your-package.nix called without required argument 'some-dependency'
</pre>
 
Usually, a dependency (some-dependency) is not available on a certain platform,
for example on <code>aarch64-darwin</code>


Submitting your change, push to your repository:
To see how other packages handle this dependency:
 
<pre>
cd nixpkgs/pkgs
grep -r some-dependency
# -r = --recursive
</pre>


<syntaxhighlight lang="bash">
===== Avoid alias =====
# recommended: create a topic branch, so that this change
# can be submitted independently from other patches:
git checkout -tb submit/your-topic-name
git push $YOUR_GITHUB_NAME submit/your-topic-name
</syntaxhighlight>


Why create your own branch? You can follow upstream (master) by running <code>git merge master</code>.
Solution 1: Replace alias names with the real package names. For example:
You can <code>git commit --amend</code> fixes and <code>git push -f</code> your branch.
You can always switch back to master by <code>git checkout master</code>.


==== Create a pull request on GitHub ====
* utillinux &rarr; util-linux
* double_conversion &rarr; double-conversion


Go to [https://github.com/nixos/nixpkgs the Nixpkgs repository] and push the ''create pull request'' button. Add a description of your work and submit.
===== Make optional =====


==== Manage your local repository ====
Solution 2: Make it an optional dependency:


Tips & tricks for managing your <code>nixpkgs</code> checkout are kept in the [[Git#Management_of_the_nixpkgs_git_repository|page on git]].
<pre>
{ lib
, stdenv
, some-dependency ? null
, another-dependency
}:


=== Becoming a Nixpkgs maintainer ===
stdenv.mkDerivation {
  buildInputs =
    [ another-dependency ]
    ++ lib.optionals (!stdenv.isDarwin) [ some-dependency ]
    # some-dependency is missing on darwin
  ;
}
</pre>


There are two types of maintainer: Members of the NixOS organization and package/module maintainer.
=== Manage your local repository ===


Members of the NixOS organization have direct access to the [https://github.com/Nixos/nixpkgs nixpkgs] and therefore can merge [[Create-pull-requests|pull requests]].
Tips & tricks for managing your <code>nixpkgs</code> checkout are kept in the [[Git#Management_of_the_nixpkgs_git_repository|page on git]].


Everybody can become a package maintainer by adding to <code>maintainers</code> attribute in the meta section of a package. First add your nick handle (preferable your GitHub username) to [https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix maintainer-list.nix] and reference the said handle within the package:
== Becoming a Nixpkgs maintainer ==


<syntaxhighlight lang="nix">{ stdenv, lib, fetchurl }:
See [https://github.com/NixOS/nixpkgs/tree/master/maintainers maintainers] in nixpkgs
stdenv.mkDerivation rec {
  name = "hello-2.10";
  # ....
  meta = with lib; {
    # ...
    maintainers = with maintainers; [ eelco your-nick ]; # replace your-nick with your real nick
    platforms = platforms.all;
  };
}</syntaxhighlight>
There can be multiple maintainers per package. Maintainers will receive emails from [[Hydra|Hydra]] when package builds enters a failed state. They do not have special privileges as everybody can suggest updates and modifications to any package. However they might be consulted by NixOS members for testing and as a domain experts, when somebody else make a change to a package.


=== Building all of the packages you maintain ===
=== Building all of the packages you maintain ===
Line 141: Line 124:
git checkout master        #1
git checkout master        #1
git fetch upstream
git fetch upstream
git rebase upstream/master
git branch -u upstream/master
</syntaxhighlight>
</syntaxhighlight>
1. make sure you're on the master branch
1. make sure you're on the master branch
after the above steps you only have to <code>git pull</code> to update the master branch


[https://stackoverflow.com/a/7244456 source]
[https://stackoverflow.com/a/7244456 source]
[[Category:Community]]
Retrieved from "https://wiki.nixos.org/wiki/Nixpkgs/Contributing"