Nixpkgs/Contributing: Difference between revisions

From NixOS Wiki
imported>Artturin
move contributing to its own subpage
 
Klinger (talk | contribs)
No edit summary
 
(15 intermediate revisions by 5 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 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 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.


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
 
# 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"  ]'


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>
# 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 99: Line 108:
nix-build maintainers/scripts/build.nix --argstr maintainer your-nick
nix-build maintainers/scripts/build.nix --argstr maintainer your-nick
</syntaxhighlight>
</syntaxhighlight>
== Maintain your nixpkgs fork ==
=== Update master ===
Add nixpkgs as a remote called upstream:
<syntaxhighlight lang="sh">
git remote add upstream https://github.com/NixOS/nixpkgs.git
</syntaxhighlight>
You only have to do it once.
<syntaxhighlight lang="sh">
git checkout master        #1
git fetch upstream
git branch -u upstream/master
</syntaxhighlight>
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]
[[Category:Community]]

Latest revision as of 20:32, 24 April 2024

Development in NixOS primarily driven by the work in 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 configuration.nix. To get your text editor to recognize Nix expressions, consider installing a Nix Editor Modes for Nix Files.

Report issues

Any issue can be reported in the 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

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.

See How to create pull requests in nixpkgs CONTRIBUTING.md.

Hack Nixpkgs

Make any modifications you want to your local copy of the repository, then build the package from the root of the nixpkgs directory with:

nix-build -A $yourpackage

The output of your build will be located under the result/ subdirectory. Try running the freshly built binaries in result/bin and check that everything is OK.

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

sudo nixos-rebuild switch -I nixpkgs=/path/to/local/nixpkgs

Run tests locally

Pushing commits to Github will run tests on Github.
We can run these tests locally, to reduce "commit noise" from failing tests

cd nixpkgs

# 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

# build
nix-build -A $yourpackage

Tests on Github:

Called without required argument

This error is produced by nixpkgs-basic-release-checks (Basic evaluation checks)

anonymous function at /path/to/your-package.nix called without required argument 'some-dependency'

Usually, a dependency (some-dependency) is not available on a certain platform, for example on aarch64-darwin

To see how other packages handle this dependency:

cd nixpkgs/pkgs
grep -r some-dependency
# -r = --recursive
Avoid alias

Solution 1: Replace alias names with the real package names. For example:

  • utillinux → util-linux
  • double_conversion → double-conversion
Make optional

Solution 2: Make it an optional dependency:

{ lib
, stdenv
, some-dependency ? null
, another-dependency
}:

stdenv.mkDerivation {
  buildInputs =
    [ another-dependency ]
    ++ lib.optionals (!stdenv.isDarwin) [ some-dependency ]
    # some-dependency is missing on darwin
  ;
}

Manage your local repository

Tips & tricks for managing your nixpkgs checkout are kept in the page on git.

Becoming a Nixpkgs maintainer

See maintainers in nixpkgs

Building all of the packages you maintain

nix-build maintainers/scripts/build.nix --argstr maintainer your-nick


Maintain your nixpkgs fork

Update master

Add nixpkgs as a remote called upstream:

git remote add upstream https://github.com/NixOS/nixpkgs.git

You only have to do it once.


git checkout master        #1
git fetch upstream
git branch -u upstream/master

1. make sure you're on the master branch

after the above steps you only have to git pull to update the master branch

source