summary refs log tree commit diff
path: root/doc/reviewing-contributions.xml
diff options
context:
space:
mode:
authorYegor Timoshenko <yegortimoshenko@gmail.com>2017-12-20 01:16:08 +0000
committerOrivej Desh <orivej@gmx.fr>2017-12-20 02:19:43 +0000
commita0aeb2381e5a6c5c57efdec1bf4b4ada44d29511 (patch)
treed4d1e931514e3341e2aa5e4ac8ca21f80751a746 /doc/reviewing-contributions.xml
parentca88a5ff9ce51a39c086532c763d8c6438296dfa (diff)
downloadnixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.tar
nixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.tar.gz
nixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.tar.bz2
nixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.tar.lz
nixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.tar.xz
nixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.tar.zst
nixlib-a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511.zip
doc: system.environmentPackages -> environment.systemPackages
Diffstat (limited to 'doc/reviewing-contributions.xml')
-rw-r--r--doc/reviewing-contributions.xml196
1 files changed, 98 insertions, 98 deletions
diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml
index 0813e0968e86..c4bd6c57ffdb 100644
--- a/doc/reviewing-contributions.xml
+++ b/doc/reviewing-contributions.xml
@@ -7,123 +7,123 @@
 <title>Reviewing contributions</title>
 
 <warning>
-  <para>The following section is a draft and reviewing policy is still being 
+  <para>The following section is a draft and reviewing policy is still being
     discussed.</para>
 </warning>
 
-<para>The nixpkgs projects receives a fairly high number of contributions via 
-  GitHub pull-requests. Reviewing and approving these is an important task and a 
+<para>The nixpkgs projects receives a fairly high number of contributions via
+  GitHub pull-requests. Reviewing and approving these is an important task and a
   way to contribute to the project.</para>
 
-<para>The high change rate of nixpkgs make any pull request that is open for 
-  long enough subject to conflicts that will require extra work from the 
-  submitter or the merger. Reviewing pull requests in a timely manner and being 
-  responsive to the comments is the key to avoid these. GitHub provides sort 
-  filters that can be used to see the <link 
-    xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most 
-    recently</link> and the <link 
-    xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least 
+<para>The high change rate of nixpkgs make any pull request that is open for
+  long enough subject to conflicts that will require extra work from the
+  submitter or the merger. Reviewing pull requests in a timely manner and being
+  responsive to the comments is the key to avoid these. GitHub provides sort
+  filters that can be used to see the <link
+    xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most
+    recently</link> and the <link
+    xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least
     recently</link> updated pull-requests.</para>
 
-<para>When reviewing a pull request, please always be nice and polite. 
-  Controversial changes can lead to controversial opinions, but it is important 
+<para>When reviewing a pull request, please always be nice and polite.
+  Controversial changes can lead to controversial opinions, but it is important
   to respect every community members and their work.</para>
 
-<para>GitHub provides reactions, they are a simple and quick way to provide 
-  feedback to pull-requests or any comments. The thumb-down reaction should be 
-  used with care and if possible accompanied with some explanations so the 
+<para>GitHub provides reactions, they are a simple and quick way to provide
+  feedback to pull-requests or any comments. The thumb-down reaction should be
+  used with care and if possible accompanied with some explanations so the
   submitter has directions to improve his contribution.</para>
 
-<para>Pull-requests reviews should include a list of what has been reviewed in a 
-  comment, so other reviewers and mergers can know the state of the 
+<para>Pull-requests reviews should include a list of what has been reviewed in a
+  comment, so other reviewers and mergers can know the state of the
   review.</para>
 
-<para>All the review template samples provided in this section are generic and 
-  meant as examples. Their usage is optional and the reviewer is free to adapt 
+<para>All the review template samples provided in this section are generic and
+  meant as examples. Their usage is optional and the reviewer is free to adapt
   them to his liking.</para>
 
 <section><title>Package updates</title>
 
-<para>A package update is the most trivial and common type of pull-request. 
-  These pull-requests mainly consist in updating the version part of the package 
+<para>A package update is the most trivial and common type of pull-request.
+  These pull-requests mainly consist in updating the version part of the package
   name and the source hash.</para>
-<para>It can happen that non trivial updates include patches or more complex 
+<para>It can happen that non trivial updates include patches or more complex
   changes.</para>
 
 <para>Reviewing process:</para>
 
 <itemizedlist>
-  <listitem><para>Add labels to the pull-request. (Requires commit 
+  <listitem><para>Add labels to the pull-request. (Requires commit
       rights)</para>
     <itemizedlist>
-      <listitem><para><literal>8.has: package (update)</literal> and any topic 
+      <listitem><para><literal>8.has: package (update)</literal> and any topic
           label that fit the updated package.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that the package versioning is fitting the 
+  <listitem><para>Ensure that the package versioning is fitting the
       guidelines.</para></listitem>
-  <listitem><para>Ensure that the commit text is fitting the 
+  <listitem><para>Ensure that the commit text is fitting the
       guidelines.</para></listitem>
   <listitem><para>Ensure that the package maintainers are notified.</para>
     <itemizedlist>
-      <listitem><para>mention-bot usually notify GitHub users based on the 
-          submitted changes, but it can happen that it misses some of the 
+      <listitem><para>mention-bot usually notify GitHub users based on the
+          submitted changes, but it can happen that it misses some of the
           package maintainers.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that the meta field contains correct 
+  <listitem><para>Ensure that the meta field contains correct
       information.</para>
     <itemizedlist>
-      <listitem><para>License can change with version updates, so it should be 
+      <listitem><para>License can change with version updates, so it should be
           checked to be fitting upstream license.</para></listitem>
-      <listitem><para>If the package has no maintainer, a maintainer must be 
-          set. This can be the update submitter or a community member that 
+      <listitem><para>If the package has no maintainer, a maintainer must be
+          set. This can be the update submitter or a community member that
           accepts to take maintainership of the package.</para></listitem>
     </itemizedlist>
   </listitem>
   <listitem><para>Ensure that the code contains no typos.</para></listitem>
   <listitem><para>Building the package locally.</para>
     <itemizedlist>
-      <listitem><para>Pull-requests are often targeted to the master or staging 
-          branch so building the pull-request locally as it is submitted can 
+      <listitem><para>Pull-requests are often targeted to the master or staging
+          branch so building the pull-request locally as it is submitted can
           trigger a large amount of source builds.</para>
-        <para>It is possible to rebase the changes on nixos-unstable or 
-          nixpkgs-unstable for easier review by running the following commands 
+        <para>It is possible to rebase the changes on nixos-unstable or
+          nixpkgs-unstable for easier review by running the following commands
           from a nixpkgs clone.
 <screen>
-$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git <co 
+$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git <co
   xml:id='reviewing-rebase-1' />
 $ git fetch channels nixos-unstable <co xml:id='reviewing-rebase-2' />
 $ git fetch origin pull/PRNUMBER/head <co xml:id='reviewing-rebase-3' />
-$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co 
+$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
   xml:id='reviewing-rebase-4' />
 </screen>
         <calloutlist>
           <callout arearefs='reviewing-rebase-1'>
-            <para>This should be done only once to be able to fetch channel 
+            <para>This should be done only once to be able to fetch channel
               branches from the nixpkgs-channels repository.</para>
           </callout>
           <callout arearefs='reviewing-rebase-2'>
             <para>Fetching the nixos-unstable branch.</para>
           </callout>
           <callout arearefs='reviewing-rebase-3'>
-            <para>Fetching the pull-request changes, <varname>PRNUMBER</varname> 
-              is the number at the end of the pull-request title and 
-              <varname>BASEBRANCH</varname> the base branch of the 
+            <para>Fetching the pull-request changes, <varname>PRNUMBER</varname>
+              is the number at the end of the pull-request title and
+              <varname>BASEBRANCH</varname> the base branch of the
               pull-request.</para>
           </callout>
           <callout arearefs='reviewing-rebase-3'>
-            <para>Rebasing the pull-request changes to the nixos-unstable 
+            <para>Rebasing the pull-request changes to the nixos-unstable
               branch.</para>
           </callout>
         </calloutlist>
         </para>
       </listitem>
       <listitem>
-        <para>The <link xlink:href="https://github.com/madjar/nox">nox</link> 
-          tool can be used to review a pull-request content in a single command. 
-          It doesn't rebase on a channel branch so it might trigger multiple 
-          source builds. <varname>PRNUMBER</varname> should be replaced by the 
+        <para>The <link xlink:href="https://github.com/madjar/nox">nox</link>
+          tool can be used to review a pull-request content in a single command.
+          It doesn't rebase on a channel branch so it might trigger multiple
+          source builds. <varname>PRNUMBER</varname> should be replaced by the
           number at the end of the pull-request title.</para>
 <screen>
 $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
@@ -153,42 +153,42 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
 
 <section><title>New packages</title>
 
-<para>New packages are a common type of pull-requests. These pull requests 
+<para>New packages are a common type of pull-requests. These pull requests
   consists in adding a new nix-expression for a package.</para>
 
 <para>Reviewing process:</para>
 
 <itemizedlist>
-  <listitem><para>Add labels to the pull-request. (Requires commit 
+  <listitem><para>Add labels to the pull-request. (Requires commit
       rights)</para>
     <itemizedlist>
-      <listitem><para><literal>8.has: package (new)</literal> and any topic 
+      <listitem><para><literal>8.has: package (new)</literal> and any topic
           label that fit the new package.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that the package versioning is fitting the 
+  <listitem><para>Ensure that the package versioning is fitting the
       guidelines.</para></listitem>
-  <listitem><para>Ensure that the commit name is fitting the 
+  <listitem><para>Ensure that the commit name is fitting the
       guidelines.</para></listitem>
-  <listitem><para>Ensure that the meta field contains correct 
+  <listitem><para>Ensure that the meta field contains correct
       information.</para>
     <itemizedlist>
-      <listitem><para>License must be checked to be fitting upstream 
+      <listitem><para>License must be checked to be fitting upstream
           license.</para></listitem>
-      <listitem><para>Platforms should be set or the package will not get binary 
+      <listitem><para>Platforms should be set or the package will not get binary
           substitutes.</para></listitem>
-      <listitem><para>A maintainer must be set, this can be the package 
-          submitter or a community member that accepts to take maintainership of 
+      <listitem><para>A maintainer must be set, this can be the package
+          submitter or a community member that accepts to take maintainership of
           the package.</para></listitem>
     </itemizedlist>
   </listitem>
   <listitem><para>Ensure that the code contains no typos.</para></listitem>
   <listitem><para>Ensure the package source.</para>
     <itemizedlist>
-      <listitem><para>Mirrors urls should be used when 
+      <listitem><para>Mirrors urls should be used when
           available.</para></listitem>
-      <listitem><para>The most appropriate function should be used (e.g. 
-          packages from GitHub should use 
+      <listitem><para>The most appropriate function should be used (e.g.
+          packages from GitHub should use
           <literal>fetchFromGitHub</literal>).</para></listitem>
     </itemizedlist>
   </listitem>
@@ -223,49 +223,49 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
 
 <section><title>Module updates</title>
 
-<para>Module updates are submissions changing modules in some ways. These often 
+<para>Module updates are submissions changing modules in some ways. These often
   contains changes to the options or introduce new options.</para>
 
 <para>Reviewing process</para>
 
 <itemizedlist>
-  <listitem><para>Add labels to the pull-request. (Requires commit 
+  <listitem><para>Add labels to the pull-request. (Requires commit
       rights)</para>
     <itemizedlist>
-      <listitem><para><literal>8.has: module (update)</literal> and any topic 
+      <listitem><para><literal>8.has: module (update)</literal> and any topic
           label that fit the module.</para></listitem>
     </itemizedlist>
   </listitem>
   <listitem><para>Ensure that the module maintainers are notified.</para>
     <itemizedlist>
-      <listitem><para>Mention-bot notify GitHub users based on the submitted 
-          changes, but it can happen that it miss some of the package 
+      <listitem><para>Mention-bot notify GitHub users based on the submitted
+          changes, but it can happen that it miss some of the package
           maintainers.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that the module tests, if any, are 
+  <listitem><para>Ensure that the module tests, if any, are
       succeeding.</para></listitem>
   <listitem><para>Ensure that the introduced options are correct.</para>
     <itemizedlist>
-      <listitem><para>Type should be appropriate (string related types differs 
-          in their merging capabilities, <literal>optionSet</literal> and 
+      <listitem><para>Type should be appropriate (string related types differs
+          in their merging capabilities, <literal>optionSet</literal> and
           <literal>string</literal> types are deprecated).</para></listitem>
-      <listitem><para>Description, default and example should be 
+      <listitem><para>Description, default and example should be
           provided.</para></listitem>
     </itemizedlist>
   </listitem>
   <listitem><para>Ensure that option changes are backward compatible.</para>
     <itemizedlist>
-      <listitem><para><literal>mkRenamedOptionModule</literal> and 
-          <literal>mkAliasOptionModule</literal> functions provide way to make 
+      <listitem><para><literal>mkRenamedOptionModule</literal> and
+          <literal>mkAliasOptionModule</literal> functions provide way to make
           option changes backward compatible.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that removed options are declared with 
+  <listitem><para>Ensure that removed options are declared with
       <literal>mkRemovedOptionModule</literal></para></listitem>
-  <listitem><para>Ensure that changes that are not backward compatible are 
+  <listitem><para>Ensure that changes that are not backward compatible are
       mentioned in release notes.</para></listitem>
-  <listitem><para>Ensure that documentations affected by the change is 
+  <listitem><para>Ensure that documentations affected by the change is
       updated.</para></listitem>
 </itemizedlist>
 
@@ -294,37 +294,37 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
 <para>New modules submissions introduce a new module to NixOS.</para>
 
 <itemizedlist>
-  <listitem><para>Add labels to the pull-request. (Requires commit 
+  <listitem><para>Add labels to the pull-request. (Requires commit
       rights)</para>
     <itemizedlist>
-      <listitem><para><literal>8.has: module (new)</literal> and any topic label 
+      <listitem><para><literal>8.has: module (new)</literal> and any topic label
           that fit the module.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that the module tests, if any, are 
+  <listitem><para>Ensure that the module tests, if any, are
       succeeding.</para></listitem>
   <listitem><para>Ensure that the introduced options are correct.</para>
     <itemizedlist>
-      <listitem><para>Type should be appropriate (string related types differs 
-          in their merging capabilities, <literal>optionSet</literal> and 
+      <listitem><para>Type should be appropriate (string related types differs
+          in their merging capabilities, <literal>optionSet</literal> and
           <literal>string</literal> types are deprecated).</para></listitem>
-      <listitem><para>Description, default and example should be 
+      <listitem><para>Description, default and example should be
           provided.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that module <literal>meta</literal> field is 
+  <listitem><para>Ensure that module <literal>meta</literal> field is
       present</para>
     <itemizedlist>
-      <listitem><para>Maintainers should be declared in 
+      <listitem><para>Maintainers should be declared in
           <literal>meta.maintainers</literal>.</para></listitem>
-      <listitem><para>Module documentation should be declared with 
+      <listitem><para>Module documentation should be declared with
           <literal>meta.doc</literal>.</para></listitem>
     </itemizedlist>
   </listitem>
-  <listitem><para>Ensure that the module respect other modules 
+  <listitem><para>Ensure that the module respect other modules
       functionality.</para>
     <itemizedlist>
-      <listitem><para>For example, enabling a module should not open firewall 
+      <listitem><para>For example, enabling a module should not open firewall
           ports by default.</para></listitem>
     </itemizedlist>
   </listitem>
@@ -340,7 +340,7 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
 - [ ] options have default
 - [ ] options have example
 - [ ] options have descriptions
-- [ ] No unneeded package is added to system.environmentPackages
+- [ ] No unneeded package is added to environment.systemPackages
 - [ ] meta.maintainers is set
 - [ ] module documentation is declared in meta.doc
 
@@ -355,22 +355,22 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
 
 <para>Other type of submissions requires different reviewing steps.</para>
 
-<para>If you consider having enough knowledge and experience in a topic and 
-  would like to be a long-term reviewer for related submissions, please contact 
-  the current reviewers for that topic. They will give you information about the 
+<para>If you consider having enough knowledge and experience in a topic and
+  would like to be a long-term reviewer for related submissions, please contact
+  the current reviewers for that topic. They will give you information about the
   reviewing process.
-The main reviewers for a topic can be hard to find as there is no list, but 
-checking past pull-requests to see who reviewed or git-blaming the code to see 
+The main reviewers for a topic can be hard to find as there is no list, but
+checking past pull-requests to see who reviewed or git-blaming the code to see
 who committed to that topic can give some hints.</para>
 
-<para>Container system, boot system and library changes are some examples of the 
+<para>Container system, boot system and library changes are some examples of the
   pull requests fitting this category.</para>
 
 </section>
 
 <section><title>Merging pull-requests</title>
 
-<para>It is possible for community members that have enough knowledge and 
+<para>It is possible for community members that have enough knowledge and
   experience on a special topic to contribute by merging pull requests.</para>
 
 <para>TODO: add the procedure to request merging rights.</para>
@@ -380,13 +380,13 @@ The following paragraph about how to deal with unactive contributors is just a
 proposition and should be modified to what the community agrees to be the right
 policy.
 
-<para>Please note that contributors with commit rights unactive for more than 
+<para>Please note that contributors with commit rights unactive for more than
   three months will have their commit rights revoked.</para>
 -->
 
-<para>In a case a contributor leaves definitively the Nix community, he should 
-  create an issue or notify the mailing list with references of packages and 
-  modules he maintains so the maintainership can be taken over by other 
+<para>In a case a contributor leaves definitively the Nix community, he should
+  create an issue or notify the mailing list with references of packages and
+  modules he maintains so the maintainership can be taken over by other
   contributors.</para>
 
 </section>