diff options
author | Yegor Timoshenko <yegortimoshenko@gmail.com> | 2017-12-20 01:16:08 +0000 |
---|---|---|
committer | Orivej Desh <orivej@gmx.fr> | 2017-12-20 02:19:43 +0000 |
commit | a0aeb2381e5a6c5c57efdec1bf4b4ada44d29511 (patch) | |
tree | d4d1e931514e3341e2aa5e4ac8ca21f80751a746 /doc/reviewing-contributions.xml | |
parent | ca88a5ff9ce51a39c086532c763d8c6438296dfa (diff) | |
download | nixlib-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.xml | 196 |
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> |