diff options
Diffstat (limited to 'pkgs/README.md')
| -rw-r--r-- | pkgs/README.md | 67 |
1 files changed, 40 insertions, 27 deletions
diff --git a/pkgs/README.md b/pkgs/README.md index a478ac120f1..31a590e43d8 100644 --- a/pkgs/README.md +++ b/pkgs/README.md @@ -29,7 +29,7 @@ We welcome new contributors of new packages to Nixpkgs, arguably the greatest so Before adding a new package, please consider the following questions: * Is the package ready for general use? We don't want to include projects that are too immature or are going to be abandoned immediately. In case of doubt, check with upstream. -* Does the project have a clear license statement? Remember that softwares are unfree by default (all rights reserved), and merely providing access to the source code does not imply its redistribution. In case of doubt, ask upstream. +* Does the project have a clear license statement? Remember that software is unfree by default (all rights reserved), and merely providing access to the source code does not imply its redistribution. In case of doubt, ask upstream. * How realistic is it that it will be used by other people? It's good that nixpkgs caters to various niches, but if it's a niche of 5 people it's probably too small. * Are you willing to maintain the package? You should care enough about the package to be willing to keep it up and running for at least one complete Nixpkgs' release life-cycle. @@ -114,6 +114,25 @@ Now that this is out of the way. To add a package to Nixpkgs: 7. Optionally commit the new package and open a pull request [to nixpkgs](https://github.com/NixOS/nixpkgs/pulls), or use [the Patches category](https://discourse.nixos.org/t/about-the-patches-category/477) on Discourse for sending a patch without a GitHub account. +## Commit conventions + +- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. + +- Format the commit messages in the following way: + + ``` + (pkg-name): (from -> to | init at version | refactor | etc) + + (Motivation for change. Link to release notes. Additional information.) + ``` + + Examples: + + * nginx: init at 2.0.1 + * firefox: 54.0.1 -> 55.0 + + https://www.mozilla.org/en-US/firefox/55.0/releasenotes/ + ## Category Hierarchy [categories]: #category-hierarchy @@ -362,25 +381,17 @@ All versions of a package _must_ be included in `all-packages.nix` to make sure * If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`. * If in doubt, try to contact the upstream developers for clarification. * `meta.mainProgram` must be set when appropriate. -* `meta.maintainers` should be set. +* `meta.maintainers` must be set for new packages. See the Nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes). ### Import From Derivation -Import From Derivation (IFD) is disallowed in Nixpkgs for performance reasons: -[Hydra] evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical. - -[Hydra]: https://github.com/NixOS/hydra +[Import From Derivation](https://nixos.org/manual/nix/unstable/language/import-from-derivation) (IFD) is disallowed in Nixpkgs for performance reasons: +[Hydra](https://github.com/NixOS/hydra) evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical. Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead. -<!-- TODO: remove the following and link to Nix manual once https://github.com/NixOS/nix/pull/7332 is merged --> - -See also [NixOS Wiki: Import From Derivation]. - -[NixOS Wiki: Import From Derivation]: https://nixos.wiki/wiki/Import_From_Derivation - ## Sources ### Fetching Sources @@ -576,7 +587,7 @@ This is how the pull request looks like in this case: [https://github.com/NixOS/ To run the main types of tests locally: - Run package-internal tests with `nix-build --attr pkgs.PACKAGE.passthru.tests` -- Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTest.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix` +- Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTests.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix` - Run [global package tests](https://nixos.org/manual/nixpkgs/unstable/#sec-package-tests) with `nix-build --attr tests.PACKAGE`, where `PACKAGE` is the name of the test listed in `pkgs/test/default.nix` - See `lib/tests/NAME.nix` for instructions on running specific library tests @@ -704,16 +715,16 @@ It can happen that non-trivial updates include patches or more complex changes. Reviewing process: -- Ensure that the package versioning fits the guidelines. -- Ensure that the commit text fits the guidelines. +- Ensure that the package versioning [fits the guidelines](#versioning). +- Ensure that the commit text [fits the guidelines](../CONTRIBUTING.md#commit-conventions). - Ensure that the package maintainers are notified. - [CODEOWNERS](https://help.github.com/articles/about-codeowners) will make GitHub notify users based on the submitted changes, but it can happen that it misses some of the package maintainers. -- Ensure that the meta field information is correct. +- Ensure that the meta field information [fits the guidelines](#meta-attributes) and is correct: - License can change with version updates, so it should be checked to match the upstream license. - 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, and building the pull request locally when it is submitted can trigger many source builds. +- Build the package locally. + - Pull requests are often targeted to the master or staging branch, and building the pull request locally when it is submitted can trigger many source builds. - 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. ```ShellSession @@ -730,7 +741,7 @@ Reviewing process: ```ShellSession $ nix-shell -p nixpkgs-review --run "nixpkgs-review pr PRNUMBER" ``` -- Running every binary. +- Run every binary. Sample template for a package update review is provided below. @@ -739,7 +750,7 @@ Sample template for a package update review is provided below. - [ ] package name fits guidelines - [ ] package version fits guidelines -- [ ] package build on ARCHITECTURE +- [ ] package builds on ARCHITECTURE - [ ] executables tested on ARCHITECTURE - [ ] all depending packages build - [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed @@ -756,18 +767,20 @@ New packages are a common type of pull requests. These pull requests consists in Review process: -- Ensure that the package versioning fits the guidelines. -- Ensure that the commit name fits the guidelines. -- Ensure that the meta fields contain correct information. +- Ensure that all file paths [fit the guidelines](../CONTRIBUTING.md#file-naming-and-organisation). +- Ensure that the package name and version [fits the guidelines](#package-naming). +- Ensure that the package versioning [fits the guidelines](#versioning). +- Ensure that the commit text [fits the guidelines](../CONTRIBUTING.md#commit-conventions). +- Ensure that the meta fields [fits the guidelines](#meta-attributes) and contain the correct information: - License must match the upstream license. - Platforms should be set (or the package will not get binary substitutes). - Maintainers must be set. This can be the package submitter or a community member that accepts taking up maintainership of the package. - Report detected typos. - Ensure the package source: - - Uses mirror URLs when available. + - Uses `mirror://` URLs when available. - Uses the most appropriate functions (e.g. packages from GitHub should use `fetchFromGitHub`). -- Building the package locally. -- Running every binary. +- Build the package locally. +- Run every binary. Sample template for a new package review is provided below. @@ -777,7 +790,7 @@ Sample template for a new package review is provided below. - [ ] package path fits guidelines - [ ] package name fits guidelines - [ ] package version fits guidelines -- [ ] package build on ARCHITECTURE +- [ ] package builds on ARCHITECTURE - [ ] executables tested on ARCHITECTURE - [ ] `meta.description` is set and fits guidelines - [ ] `meta.license` fits upstream license |