459 lines
14 KiB
XML
459 lines
14 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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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="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>
|
|
<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>
|
|
|