From aae774571e6faeb166f9d4fbfca6afbfc6aa21af Mon Sep 17 00:00:00 2001 From: Samuel Leathers Date: Sat, 26 Aug 2017 11:21:29 -0400 Subject: doc: explain pull request template --- doc/submitting-changes.xml | 127 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) (limited to 'doc/submitting-changes.xml') diff --git a/doc/submitting-changes.xml b/doc/submitting-changes.xml index 0b09dffbb2d3..c8742a083c39 100644 --- a/doc/submitting-changes.xml +++ b/doc/submitting-changes.xml @@ -223,6 +223,133 @@ Additional information. +
+ Pull Request Template + + 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. + + When a PR is created, it will be pre-populated with some checkboxes detailed below: + +
+ Tested using sandboxing + + 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 + fetch* 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 build-use-sandbox + in Nix manual for details. + + + Sandboxing is not enabled by default in Nix due to a small performance + hit on each build. In pull requests for nixpkgs people + are asked to test builds with sandboxing enabled (see Tested + using sandboxing in the pull request template) because + inhttps://nixos.org/hydra/ + sandboxing is also used. + + + Depending if you use NixOS or other platforms you can use one of the + following methods to enable sandboxing before building the package: + + + + Globally enable sandboxing on NixOS: + add the following to + configuration.nix + nix.useSandbox = true; + + + + + Globally enable sandboxing on non-NixOS platforms: + add the following to: /etc/nix/nix.conf + build-use-sandbox = true + + + + + +
+
+ Built on platform(s) + + 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. + +
+
+ Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests) + + 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 section + in the NixOS manual. + +
+
+ Tested compilation of all pkgs that depend on this change using <command>nox-review</command> + + 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 nox-review + utility can look for and build all dependencies either based on + uncommited changes with the wip option or specifying a + github pull request number. + + + review uncommitted changes: + nix-shell -p nox --run nox-review wip + + + review changes from pull request number 12345: + nix-shell -p nox --run nox-review pr 12345 + +
+
+ Tested execution of all binary files (usually in <filename>./result/bin/</filename>) + + 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 + ./result/bin and running any files in there, or at a + minimum, the main executable for the package. For example, if you make a change + to texlive, you probably would only check the binaries + associated with the change you made rather than testing all of them. + +
+
+ Meets nixpkgs contribution standards + + The last checkbox is fits CONTRIBUTING.md. + 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. + + +
+
+
Hotfixing pull requests -- cgit v1.2.3