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 @@ Reviewing contributions - The following section is a draft and reviewing policy is still being + The following section is a draft and reviewing policy is still being discussed. -The nixpkgs projects receives a fairly high number of contributions via - GitHub pull-requests. Reviewing and approving these is an important task and a +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. -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 most - recently and the least +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 most + recently and the least recently updated pull-requests. -When reviewing a pull request, please always be nice and polite. - Controversial changes can lead to controversial opinions, but it is important +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. -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 +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. -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 +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. -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 +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.
Package updates -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 +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. -It can happen that non trivial updates include patches or more complex +It can happen that non trivial updates include patches or more complex changes. Reviewing process: - Add labels to the pull-request. (Requires commit + Add labels to the pull-request. (Requires commit rights) - 8.has: package (update) and any topic + 8.has: package (update) and any topic label that fit the updated package. - Ensure that the package versioning is fitting the + Ensure that the package versioning is fitting the guidelines. - Ensure that the commit text is fitting the + Ensure that the commit text is fitting the guidelines. Ensure that the package maintainers are notified. - mention-bot usually notify GitHub users based on the - submitted changes, but it can happen that it misses some of the + mention-bot usually notify GitHub users based on the + submitted changes, but it can happen that it misses some of the package maintainers. - Ensure that the meta field contains correct + Ensure that the meta field contains correct information. - License can change with version updates, so it should be + License can change with version updates, so it should be checked to be fitting upstream license. - If the package has no maintainer, a maintainer must be - set. This can be the update submitter or a community member that + 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. Ensure that the code contains no typos. Building the package locally. - Pull-requests are often targeted to the master or staging - branch so building the pull-request locally as it is submitted can + 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. - It is possible to rebase the changes on nixos-unstable or - nixpkgs-unstable for easier review by running the following commands + 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. -$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git $ git fetch channels nixos-unstable $ git fetch origin pull/PRNUMBER/head -$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD - This should be done only once to be able to fetch channel + This should be done only once to be able to fetch channel branches from the nixpkgs-channels repository. Fetching the nixos-unstable branch. - Fetching the pull-request changes, PRNUMBER - is the number at the end of the pull-request title and - BASEBRANCH the base branch of the + Fetching the pull-request changes, PRNUMBER + is the number at the end of the pull-request title and + BASEBRANCH the base branch of the pull-request. - Rebasing the pull-request changes to the nixos-unstable + Rebasing the pull-request changes to the nixos-unstable branch. - The nox - 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. PRNUMBER should be replaced by the + The nox + 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. PRNUMBER should be replaced by the number at the end of the pull-request title. $ nix-shell -p nox --run "nox-review -k pr PRNUMBER" @@ -153,42 +153,42 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
New packages -New packages are a common type of pull-requests. These pull requests +New packages are a common type of pull-requests. These pull requests consists in adding a new nix-expression for a package. Reviewing process: - Add labels to the pull-request. (Requires commit + Add labels to the pull-request. (Requires commit rights) - 8.has: package (new) and any topic + 8.has: package (new) and any topic label that fit the new package. - Ensure that the package versioning is fitting the + Ensure that the package versioning is fitting the guidelines. - Ensure that the commit name is fitting the + Ensure that the commit name is fitting the guidelines. - Ensure that the meta field contains correct + Ensure that the meta field contains correct information. - License must be checked to be fitting upstream + License must be checked to be fitting upstream license. - Platforms should be set or the package will not get binary + Platforms should be set or the package will not get binary substitutes. - A maintainer must be set, this can be the package - submitter or a community member that accepts to take maintainership of + A maintainer must be set, this can be the package + submitter or a community member that accepts to take maintainership of the package. Ensure that the code contains no typos. Ensure the package source. - Mirrors urls should be used when + Mirrors urls should be used when available. - The most appropriate function should be used (e.g. - packages from GitHub should use + The most appropriate function should be used (e.g. + packages from GitHub should use fetchFromGitHub). @@ -223,49 +223,49 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
Module updates -Module updates are submissions changing modules in some ways. These often +Module updates are submissions changing modules in some ways. These often contains changes to the options or introduce new options. Reviewing process - Add labels to the pull-request. (Requires commit + Add labels to the pull-request. (Requires commit rights) - 8.has: module (update) and any topic + 8.has: module (update) and any topic label that fit the module. Ensure that the module maintainers are notified. - Mention-bot notify GitHub users based on the submitted - changes, but it can happen that it miss some of the package + Mention-bot notify GitHub users based on the submitted + changes, but it can happen that it miss some of the package maintainers. - Ensure that the module tests, if any, are + Ensure that the module tests, if any, are succeeding. Ensure that the introduced options are correct. - Type should be appropriate (string related types differs - in their merging capabilities, optionSet and + Type should be appropriate (string related types differs + in their merging capabilities, optionSet and string types are deprecated). - Description, default and example should be + Description, default and example should be provided. Ensure that option changes are backward compatible. - mkRenamedOptionModule and - mkAliasOptionModule functions provide way to make + mkRenamedOptionModule and + mkAliasOptionModule functions provide way to make option changes backward compatible. - Ensure that removed options are declared with + Ensure that removed options are declared with mkRemovedOptionModule - Ensure that changes that are not backward compatible are + Ensure that changes that are not backward compatible are mentioned in release notes. - Ensure that documentations affected by the change is + Ensure that documentations affected by the change is updated. @@ -294,37 +294,37 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER" New modules submissions introduce a new module to NixOS. - Add labels to the pull-request. (Requires commit + Add labels to the pull-request. (Requires commit rights) - 8.has: module (new) and any topic label + 8.has: module (new) and any topic label that fit the module. - Ensure that the module tests, if any, are + Ensure that the module tests, if any, are succeeding. Ensure that the introduced options are correct. - Type should be appropriate (string related types differs - in their merging capabilities, optionSet and + Type should be appropriate (string related types differs + in their merging capabilities, optionSet and string types are deprecated). - Description, default and example should be + Description, default and example should be provided. - Ensure that module meta field is + Ensure that module meta field is present - Maintainers should be declared in + Maintainers should be declared in meta.maintainers. - Module documentation should be declared with + Module documentation should be declared with meta.doc. - Ensure that the module respect other modules + Ensure that the module respect other modules functionality. - For example, enabling a module should not open firewall + For example, enabling a module should not open firewall ports by default. @@ -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" Other type of submissions requires different reviewing steps. -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 +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. -Container system, boot system and library changes are some examples of the +Container system, boot system and library changes are some examples of the pull requests fitting this category.
Merging pull-requests -It is possible for community members that have enough knowledge and +It is possible for community members that have enough knowledge and experience on a special topic to contribute by merging pull requests. TODO: add the procedure to request merging rights. @@ -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. -Please note that contributors with commit rights unactive for more than +Please note that contributors with commit rights unactive for more than three months will have their commit rights revoked. --> -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 +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.
diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml index bc352609944b..9c2c59006f15 100644 --- a/nixos/doc/manual/configuration/x-windows.xml +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -130,7 +130,7 @@ Note: the use of services.xserver.synaptics is deprecated sin GTK/Qt themes GTK themes can be installed either to user profile or system-wide (via -system.environmentPackages). To make Qt 5 applications look similar +environment.systemPackages). To make Qt 5 applications look similar to GTK2 ones, you can install qt5.qtbase.gtk package into your system environment. It should work for all Qt 5 library versions.