Official NixOS Wiki

Nixpkgs/Contributing: Difference between revisions

← Older edit
VisualWikitext
imported>Artturin
No edit summary
m Grammar fix
 
(16 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Contributing ==
Development in NixOS is 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 nixpkgs issue-tracker [https://github.com/nixos/nixpkgs/issues 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 be 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 finally merge into the repository.


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.
See [https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#how-to-create-pull-requests How to create pull requests] in nixpkgs CONTRIBUTING.md.


Here's how to create a pull request on GitHub:
=== Hack Nixpkgs ===


==== Fork Nixpkgs on Github ====
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>


Create a GitHub account and fork nixpkgs/nixos/... repository.  
The output of your build will be located under the <code>result/</code> subdirectory. Try running the freshly built binaries in <code>result/bin</code> and check that everything is OK.


==== Add a remote ====
To test the changes on a NixOS machine, rebuild the system using your newly hacked Nixpkgs by executing:


On your host, create a new remote location:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# add your github clone as remote location:
sudo nixos-rebuild switch -I nixpkgs=/path/to/local/nixpkgs
YOUR_GITHUB_NAME=fill-in
git remote add $YOUR_GITHUB_NAME git@github.com:$YOUR_GITHUB_NAME/nixpkgs.git
</syntaxhighlight>
</syntaxhighlight>


==== Hack Nixpkgs ====
=== Run tests locally ===
 
Pushing commits to Github will run tests on Github.<br>
We can run these tests locally, to reduce "commit noise" from failing tests
 
<pre>
cd 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>
# Basic evaluation checks
nix-build pkgs/top-level/release.nix -A tarball.nixpkgs-basic-release-checks \
--arg supportedSystems '[ "aarch64-darwin" "aarch64-linux" "x86_64-linux" "x86_64-darwin" ]'
 
# list all derivations
nix-env --query --available --out-path --file ./. --show-trace


The output of your build will be located under the <code>result/</code> subdirectory. Try running the freshly built binaries in <code>result/bin</code> and check that everything is OK.
# build
nix-build -A $yourpackage
</pre>


To test the changes on a NixOS machine, rebuild the system using your newly hacked Nixpkgs by executing:
Tests on Github:


<syntaxhighlight lang="bash">
* [https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/basic-eval.yml Basic evaluation checks]
sudo nixos-rebuild switch -I nixpkgs=/path/to/local/nixpkgs
* [https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/editorconfig.yml Checking EditorConfig]
</syntaxhighlight>
** Read https://editorconfig.org/#download to configure your editor
* [https://github.com/NixOS/ofborg#how-does-ofborg-call-nix-build ofborg-eval] will call <code>nix-build -A $yourpackage</code>


==== Commit your change locally ====
==== Called without required argument ====


Commit your change to your local clone of the repository:
This error is produced by <code>nixpkgs-basic-release-checks</code> (Basic evaluation checks)
<syntaxhighlight lang="bash">
git add FILE_LIST # use git add --patch as needed
git commit


==== Check status ====
<pre>
anonymous function at /path/to/your-package.nix called without required argument 'some-dependency'
</pre>


Verify everything is ok - no unexpected dangling files git does not know about yet:
Usually, a dependency (some-dependency) is not available on a certain platform,
git status
for example on <code>aarch64-darwin</code>
</syntaxhighlight>


==== Push to your remote repository ====
To see how other packages handle this dependency:


Submitting your change, push to your repository:
<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, fetchurl }:
See [https://github.com/NixOS/nixpkgs/tree/master/maintainers maintainers] in nixpkgs
stdenv.mkDerivation rec {
  name = "hello-2.10";
  # ....
  meta = with stdenv.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 115: 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"