path: root/doc/contributing/submitting-changes.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>
<prompt>$ </prompt>git checkout 0998212
<prompt>$ </prompt>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/&lt;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 &lt;path to your local nixpkgs folder&gt;</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 &lt;path to your local nixpkgs folder&gt;</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 &lt;path to your local nixpkgs folder&gt;/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=&lt;path to your local nixpkgs folder&gt; --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/&lt;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/#conf-sandbox">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>sandbox = true</screen>
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </section>

  <section xml:id="submitting-changes-platform-diversity">
   <title>Built on platform(s)</title>

   <para>