forked from mirrors/nixpkgs
524 lines
16 KiB
XML
524 lines
16 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="chap-submitting-changes">
|
|
<title>Submitting changes</title>
|
|
<section xml:id="submitting-changes-making-patches">
|
|
<title>Making patches</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Read <link xlink:href="https://nixos.org/nixpkgs/manual/">Manual (How to
|
|
write packages for Nix)</link>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Fork the repository on GitHub.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Create a branch for your future fix.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
You can make branch from a commit of your local
|
|
<command>nixos-version</command>. That will help you to avoid
|
|
additional local compilations. Because you will receive packages from
|
|
binary cache.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
For example: <command>nixos-version</command> returns
|
|
<command>15.05.git.0998212 (Dingo)</command>. So you can do:
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<screen>
|
|
$ git checkout 0998212
|
|
$ git checkout -b 'fix/pkg-name-update'
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Please avoid working directly on the <command>master</command> branch.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Make commits of logical units.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If you removed pkgs, made some major NixOS changes etc., write about
|
|
them in
|
|
<command>nixos/doc/manual/release-notes/rl-unstable.xml</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Check for unnecessary whitespace with <command>git diff --check</command>
|
|
before committing.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Format the commit in a following way:
|
|
</para>
|
|
<programlisting>
|
|
(pkg-name | nixos/<module>): (from -> to | init at version | refactor | etc)
|
|
Additional information.
|
|
</programlisting>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Examples:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<command>nginx: init at 2.0.1</command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<command>firefox: 54.0.1 -> 55.0</command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<command>nixos/hydra: add bazBaz option</command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<command>nixos/nginx: refactor config generation</command>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Test your changes. If you work with
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
nixpkgs:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
update pkg ->
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<command>nix-env -i pkg-name -f <path to your local nixpkgs
|
|
folder></command>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
add pkg ->
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Make sure it's in
|
|
<command>pkgs/top-level/all-packages.nix</command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<command>nix-env -i pkg-name -f <path to your local nixpkgs
|
|
folder></command>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>If you don't want to install pkg in you
|
|
profile</emphasis>.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<command>nix-build -A pkg-attribute-name <path to your local
|
|
nixpkgs folder>/default.nix</command> and check results in the
|
|
folder <command>result</command>. It will appear in the same
|
|
directory where you did <command>nix-build</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If you did <command>nix-env -i pkg-name</command> you can do
|
|
<command>nix-env -e pkg-name</command> to uninstall it from your
|
|
system.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
NixOS and its modules:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
You can add new module to your NixOS configuration file (usually
|
|
it's <command>/etc/nixos/configuration.nix</command>). And do
|
|
<command>sudo nixos-rebuild test -I nixpkgs=<path to your local
|
|
nixpkgs folder> --fast</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If you have commits <command>pkg-name: oh, forgot to insert
|
|
whitespace</command>: squash commits in this case. Use <command>git rebase
|
|
-i</command>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Rebase you branch against current <command>master</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="submitting-changes-submitting-changes">
|
|
<title>Submitting changes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Push your changes to your fork of nixpkgs.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Create pull request:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Write the title in format <command>(pkg-name | nixos/<module>):
|
|
improvement</command>.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If you update the pkg, write versions <command>from -> to</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Write in comment if you have tested your patch. Do not rely much on
|
|
<command>TravisCI</command>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If you make an improvement, write about your motivation.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Notify maintainers of the package. For example add to the message:
|
|
<command>cc @jagajaga @domenkozar</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="submitting-changes-pull-request-template">
|
|
<title>Pull Request Template</title>
|
|
|
|
<para>
|
|
The pull request template helps determine what steps have been made for a
|
|
contribution so far, and will help guide maintainers on the status of a
|
|
change. The motivation section of the PR should include any extra details
|
|
the title does not address and link any existing issues related to the pull
|
|
request.
|
|
</para>
|
|
|
|
<para>
|
|
When a PR is created, it will be pre-populated with some checkboxes detailed
|
|
below:
|
|
</para>
|
|
|
|
<section xml:id="submitting-changes-tested-with-sandbox">
|
|
<title>Tested using sandboxing</title>
|
|
|
|
<para>
|
|
When sandbox builds are enabled, Nix will setup an isolated environment for
|
|
each build process. It is used to remove further hidden dependencies set by
|
|
the build environment to improve reproducibility. This includes access to
|
|
the network during the build outside of <function>fetch*</function>
|
|
functions and files outside the Nix store. Depending on the operating
|
|
system access to other resources are blocked as well (ex. inter process
|
|
communication is isolated on Linux); see
|
|
<link
|
|
xlink:href="https://nixos.org/nix/manual/#description-45">build-use-sandbox</link>
|
|
in Nix manual for details.
|
|
</para>
|
|
|
|
<para>
|
|
Sandboxing is not enabled by default in Nix due to a small performance hit
|
|
on each build. In pull requests for
|
|
<link
|
|
xlink:href="https://github.com/NixOS/nixpkgs/">nixpkgs</link>
|
|
people are asked to test builds with sandboxing enabled (see
|
|
<literal>Tested using sandboxing</literal> in the pull request template)
|
|
because
|
|
in<link
|
|
xlink:href="https://nixos.org/hydra/">https://nixos.org/hydra/</link>
|
|
sandboxing is also used.
|
|
</para>
|
|
|
|
<para>
|
|
Depending if you use NixOS or other platforms you can use one of the
|
|
following methods to enable sandboxing
|
|
<emphasis role="bold">before</emphasis> building the package:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">Globally enable sandboxing on NixOS</emphasis>:
|
|
add the following to <filename>configuration.nix</filename>
|
|
<screen>nix.useSandbox = true;</screen>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">Globally enable sandboxing on non-NixOS
|
|
platforms</emphasis>: add the following to:
|
|
<filename>/etc/nix/nix.conf</filename>
|
|
<screen>build-use-sandbox = true</screen>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-platform-diversity">
|
|
<title>Built on platform(s)</title>
|
|
|
|
<para>
|
|
Many Nix packages are designed to run on multiple platforms. As such, it's
|
|
important to let the maintainer know which platforms your changes have been
|
|
tested on. It's not always practical to test a change on all platforms, and
|
|
is not required for a pull request to be merged. Only check the systems you
|
|
tested the build on in this section.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-nixos-tests">
|
|
<title>Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)</title>
|
|
|
|
<para>
|
|
Packages with automated tests are much more likely to be merged in a timely
|
|
fashion because it doesn't require as much manual testing by the maintainer
|
|
to verify the functionality of the package. If there are existing tests for
|
|
the package, they should be run to verify your changes do not break the
|
|
tests. Tests only apply to packages with NixOS modules defined and can only
|
|
be run on Linux. For more details on writing and running tests, see the
|
|
<link
|
|
xlink:href="https://nixos.org/nixos/manual/index.html#sec-nixos-tests">section
|
|
in the NixOS manual</link>.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-tested-compilation">
|
|
<title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title>
|
|
|
|
<para>
|
|
If you are updating a package's version, you can use nox to make sure all
|
|
packages that depend on the updated package still compile correctly. This
|
|
can be done using the nox utility. The <command>nox-review</command>
|
|
utility can look for and build all dependencies either based on uncommited
|
|
changes with the <literal>wip</literal> option or specifying a github pull
|
|
request number.
|
|
</para>
|
|
|
|
<para>
|
|
review uncommitted changes:
|
|
<screen>nix-shell -p nox --run "nox-review wip"</screen>
|
|
</para>
|
|
|
|
<para>
|
|
review changes from pull request number 12345:
|
|
<screen>nix-shell -p nox --run "nox-review pr 12345"</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-tested-execution">
|
|
<title>Tested execution of all binary files (usually in <filename>./result/bin/</filename>)</title>
|
|
|
|
<para>
|
|
It's important to test any executables generated by a build when you change
|
|
or create a package in nixpkgs. This can be done by looking in
|
|
<filename>./result/bin</filename> and running any files in there, or at a
|
|
minimum, the main executable for the package. For example, if you make a
|
|
change to <package>texlive</package>, you probably would only check the
|
|
binaries associated with the change you made rather than testing all of
|
|
them.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-contribution-standards">
|
|
<title>Meets Nixpkgs contribution standards</title>
|
|
|
|
<para>
|
|
The last checkbox is fits
|
|
<link
|
|
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md">CONTRIBUTING.md</link>.
|
|
The contributing document has detailed information on standards the Nix
|
|
community has for commit messages, reviews, licensing of contributions you
|
|
make to the project, etc... Everyone should read and understand the
|
|
standards the community has for contributing before submitting a pull
|
|
request.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section xml:id="submitting-changes-hotfixing-pull-requests">
|
|
<title>Hotfixing pull requests</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Make the appropriate changes in you branch.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Don't create additional commits, do
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<command>git rebase -i</command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<command>git push --force</command> to your branch.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="submitting-changes-commit-policy">
|
|
<title>Commit policy</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Commits must be sufficiently tested before being merged, both for the
|
|
master and staging branches.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Hydra builds for master and staging should not be used as testing
|
|
platform, it's a build farm for changes that have been already tested.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
When changing the bootloader installation process, extra care must be
|
|
taken. Grub installations cannot be rolled back, hence changes may break
|
|
people's installations forever. For any non-trivial change to the
|
|
bootloader please file a PR asking for review, especially from @edolstra.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section xml:id="submitting-changes-master-branch">
|
|
<title>Master branch</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It should only see non-breaking commits that do not cause mass rebuilds.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-staging-branch">
|
|
<title>Staging branch</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It's only for non-breaking mass-rebuild commits. That means it's not to
|
|
be used for testing, and changes must have been well tested already.
|
|
<link xlink:href="https://web.archive.org/web/20160528180406/http://comments.gmane.org/gmane.linux.distributions.nixos/13447">Read
|
|
policy here</link>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the branch is already in a broken state, please refrain from adding
|
|
extra new breakages. Stabilize it for a few days, merge into master, then
|
|
resume development on staging.
|
|
<link xlink:href="http://hydra.nixos.org/jobset/nixpkgs/staging#tabs-evaluations">Keep
|
|
an eye on the staging evaluations here</link>. If any fixes for staging
|
|
happen to be already in master, then master can be merged into staging.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="submitting-changes-stable-release-branches">
|
|
<title>Stable release branches</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If you're cherry-picking a commit to a stable release branch, always use
|
|
<command>git cherry-pick -xe</command> and ensure the message contains a
|
|
clear description about why this needs to be included in the stable
|
|
branch.
|
|
</para>
|
|
<para>
|
|
An example of a cherry-picked commit would look like this:
|
|
</para>
|
|
<screen>
|
|
nixos: Refactor the world.
|
|
|
|
The original commit message describing the reason why the world was torn apart.
|
|
|
|
(cherry picked from commit abcdef)
|
|
Reason: I just had a gut feeling that this would also be wanted by people from
|
|
the stone age.
|
|
</screen>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</chapter>
|