diff options
Diffstat (limited to 'doc/submitting-changes.xml')
| -rw-r--r-- | doc/submitting-changes.xml | 860 |
1 files changed, 462 insertions, 398 deletions
diff --git a/doc/submitting-changes.xml b/doc/submitting-changes.xml index d3cf221c9b69..ffa3a90b5eb6 100644 --- a/doc/submitting-changes.xml +++ b/doc/submitting-changes.xml @@ -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> -<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> + </listitem> + <listitem> + <para> + Please avoid working directly on the <command>master</command> branch. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> <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. + 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> - 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. + Check for unnecessary whitespace with <command>git diff --check</command> + before committing. </para> + </listitem> + <listitem> <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> + 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> - <emphasis role="bold">Globally enable sandboxing on NixOS</emphasis>: - add the following to - <filename>configuration.nix</filename> - <screen>nix.useSandbox = true;</screen> - </para> + <para> + <command>nginx: init at 2.0.1</command> + </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> + <para> + <command>firefox: 54.0.1 -> 55.0</command> + </para> </listitem> - </itemizedlist> - </para> - - </section> - <section> - <title>Built on platform(s)</title> + <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> - 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. + 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> - </section> - <section> - <title>Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)</title> + </listitem> + <listitem> <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>. + 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> - </section> - <section> - <title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title> + </listitem> + <listitem> <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. + Rebase you branch against current <command>master</command>. </para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Submitting changes</title> + + <itemizedlist> + <listitem> <para> - review uncommitted changes: - <screen>nix-shell -p nox --run "nox-review wip"</screen> + Push your changes to your fork of nixpkgs. </para> + </listitem> + <listitem> <para> - review changes from pull request number 12345: - <screen>nix-shell -p nox --run "nox-review pr 12345"</screen> + 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> - </section> + </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 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 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>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> - + <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> - -<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 + <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> -<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> + <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> -</itemizedlist> -</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>Commit policy</title> + <section> + <title>Meets nixpkgs contribution standards</title> -<itemizedlist> -<listitem> -<para>Commits must be sufficiently tested before being merged, both for the master and staging branches.</para> -</listitem> + <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> -<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> + <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> -<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> + <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> + <title>Master branch</title> - <itemizedlist> + <itemizedlist> <listitem> - <para> - It should only see non-breaking commits that do not cause mass rebuilds. - </para> + <para> + It should only see non-breaking commits that do not cause mass rebuilds. + </para> </listitem> - </itemizedlist> -</section> + </itemizedlist> + </section> -<section> - <title>Staging branch</title> + <section> + <title>Staging branch</title> - <itemizedlist> + <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> + <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> + <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> + </itemizedlist> + </section> -<section> - <title>Stable release branches</title> + <section> + <title>Stable release branches</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> + 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> - |