From a7f4fd00149d30651d1b16f708a95e5b76950d63 Mon Sep 17 00:00:00 2001 From: Wael Nasreddine Date: Fri, 8 Mar 2019 21:07:11 -0800 Subject: doc: format the documentation (#57102) --- doc/coding-conventions.xml | 98 ++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 47 deletions(-) (limited to 'doc/coding-conventions.xml') diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index d2c7a1baae9c..58ce9c7e627c 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -197,20 +197,14 @@ args.stdenv.mkDerivation (args // { Package naming - The key words - must, - must not, - required, - shall, - shall not, - should, - should not, - recommended, - may, - and optional in this section - are to be interpreted as described in - RFC 2119. - Only emphasized words are to be interpreted in this way. + The key words must, must not, + required, shall, shall + not, should, should + not, recommended, may, + and optional in this section are to be interpreted as + described in RFC + 2119. Only emphasized words are to be + interpreted in this way. @@ -253,15 +247,15 @@ args.stdenv.mkDerivation (args // { - The name attribute should - be identical to the upstream package name. + The name attribute should be + identical to the upstream package name. - The name attribute must not - contain uppercase letters — e.g., "mplayer-1.0rc2" - instead of "MPlayer-1.0rc2". + The name attribute must not + contain uppercase letters — e.g., "mplayer-1.0rc2" + instead of "MPlayer-1.0rc2". @@ -275,28 +269,29 @@ args.stdenv.mkDerivation (args // { If a package is not a release but a commit from a repository, then the version part of the name must be the date of that - (fetched) commit. The date must be in "YYYY-MM-DD" - format. Also append "unstable" to the name - e.g., + (fetched) commit. The date must be in + "YYYY-MM-DD" format. Also append + "unstable" to the name - e.g., "pkgname-unstable-2014-09-23". - Dashes in the package name should be preserved in new variable names, - rather than converted to underscores or camel cased — e.g., - http-parser instead of http_parser - or httpParser. The hyphenated style is preferred in - all three package names. + Dashes in the package name should be preserved in + new variable names, rather than converted to underscores or camel cased + — e.g., http-parser instead of + http_parser or httpParser. The + hyphenated style is preferred in all three package names. - If there are multiple versions of a package, this should be reflected in - the variable names in all-packages.nix, e.g. - json-c-0-9 and json-c-0-11. If - there is an obvious “default” version, make an attribute like - json-c = json-c-0-9;. See also - + If there are multiple versions of a package, this + should be reflected in the variable names in + all-packages.nix, e.g. json-c-0-9 + and json-c-0-11. If there is an obvious “default” + version, make an attribute like json-c = json-c-0-9;. + See also @@ -814,8 +809,8 @@ args.stdenv.mkDerivation (args // { There are multiple ways to fetch a package source in nixpkgs. The general - guideline is that you should package reproducible sources with a high degree of - availability. Right now there is only one fetcher which has mirroring + guideline is that you should package reproducible sources with a high degree + of availability. Right now there is only one fetcher which has mirroring support and that is fetchurl. Note that you should also prefer protocols which have a corresponding proxy environment variable. @@ -869,8 +864,10 @@ src = fetchFromGitHub { } Find the value to put as sha256 by running - nix run -f '<nixpkgs>' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix - or nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz. + nix run -f '<nixpkgs>' nix-prefetch-github -c + nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS + nix or nix-prefetch-url --unpack + https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz. @@ -953,17 +950,23 @@ $ nix-hash --type sha256 --to-base32 HASH would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash. - This method has security problems. Check below for details. + + + This method has security problems. Check below for details. + +
Obtaining hashes securely + - Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching - source you can fetch malware, and instead of source hash you get hash of malware. Here are - security considerations for this scenario: + Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead + of fetching source you can fetch malware, and instead of source hash you + get hash of malware. Here are security considerations for this scenario: + @@ -972,7 +975,8 @@ $ nix-hash --type sha256 --to-base32 HASH - hashes from upstream (in method 3) should be obtained via secure protocol; + hashes from upstream (in method 3) should be obtained via secure + protocol; @@ -982,12 +986,12 @@ $ nix-hash --type sha256 --to-base32 HASH - https:// URLs are not secure in method 5. When obtaining hashes - with fake hash method, TLS checks are disabled. So - refetch source hash from several different networks to exclude MITM scenario. - Alternatively, use fake hash method to make Nix error, but instead of extracting - hash from error, extract https:// URL and prefetch it - with method 1. + https:// URLs are not secure in method 5. When + obtaining hashes with fake hash method, TLS checks are disabled. So + refetch source hash from several different networks to exclude MITM + scenario. Alternatively, use fake hash method to make Nix error, but + instead of extracting hash from error, extract + https:// URL and prefetch it with method 1. -- cgit v1.2.3