nixpkgs docs: format =)
This commit is contained in:
Graham Christensen
+471
-407
@@ -1,447 +1,513 @@
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
</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>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>
|
||||
<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.
|
||||
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>
|
||||
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
|
||||
<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
|
||||
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>
|
||||
|
||||
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>
|
||||
<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
|
||||
<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>
|
||||
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>
|
||||
<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>
|
||||
<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
|
||||
<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>
|
||||
|
||||
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>
|
||||
</section>
|
||||
<section>
|
||||
<title>Hotfixing pull requests</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
It should only see non-breaking commits that do not cause mass rebuilds.
|
||||
</para>
|
||||
</listitem>
|
||||
<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>Staging branch</title>
|
||||
</section>
|
||||
<section>
|
||||
<title>Commit policy</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>
|
||||
<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>
|
||||
|
||||
<section>
|
||||
<title>Stable release branches</title>
|
||||
<section>
|
||||
<title>Master branch</title>
|
||||
|
||||
<itemizedlist>
|
||||
<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>
|
||||
<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.
|
||||
@@ -451,9 +517,7 @@ Reason: I just had a gut feeling that this would also be wanted by people from
|
||||
the stone age.
|
||||
</screen>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user