From 3a0707f0c7823b30bd0264768756671b6eb1b4c9 Mon Sep 17 00:00:00 2001 From: Cillian de Róiste Date: Sat, 11 Jul 2015 19:57:28 +0200 Subject: Move the details from CONTRIBUTING.md to the manual #8734 --- doc/submitting-changes.xml | 283 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 doc/submitting-changes.xml (limited to 'doc/submitting-changes.xml') diff --git a/doc/submitting-changes.xml b/doc/submitting-changes.xml new file mode 100644 index 000000000000..fe331d082506 --- /dev/null +++ b/doc/submitting-changes.xml @@ -0,0 +1,283 @@ + + +Submitting changes + +
+Making patches + + + +Read Manual (How to write packages for Nix). + + + +Fork the repository on GitHub. + + + +Create a branch for your future fix. + + + +You can make branch from a commit of your local nixos-version. That will help you to avoid additional local compilations. Because you will receive packages from binary cache. + + + +For example: nixos-version returns 15.05.git.0998212 (Dingo). So you can do: + + + + +$ git checkout 0998212 +$ git checkout -b 'fix/pkg-name-update' + + + + + +Please avoid working directly on the master branch. + + + + + + +Make commits of logical units. + + + +If you removed pkgs, made some major NixOS changes etc., write about them in nixos/doc/manual/release-notes/rl-unstable.xml. + + + + + + +Check for unnecessary whitespace with git diff --check before committing. + + + +Format the commit in a following way: + +(pkg-name | service-name): (from -> to | init at version | refactor | etc) +Additional information. + + + + +Examples: + + + + +nginx: init at 2.0.1 + + + + + +firefox: 3.0 -> 3.1.1 + + + + + +hydra service: add bazBaz option + + + + + +nginx service: refactor config generation + + + + + + + + + +Test your changes. If you work with + + + +nixpkgs: + + + +update pkg -> + + + + +nix-env -i pkg-name -f <path to your local nixpkgs folder> + + + + + + + +add pkg -> + + + +Make sure it's in pkgs/top-level/all-packages.nix + + + + + +nix-env -i pkg-name -f <path to your local nixpkgs folder> + + + + + + + + +If you don't want to install pkg in you profile. + + + + +nix-build -A pkg-attribute-name <path to your local nixpkgs folder>/default.nix and check results in the folder result. It will appear in the same directory where you did nix-build. + + + + + + +If you did nix-env -i pkg-name you can do nix-env -e pkg-name to uninstall it from your system. + + + + + + +NixOS and its modules: + + + +You can add new module to your NixOS configuration file (usually it's /etc/nixos/configuration.nix). + And do sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast. + + + + + + + + + +If you have commits pkg-name: oh, forgot to insert whitespace: squash commits in this case. Use git rebase -i. + + + +Rebase you branch against current master. + + +
+ +
+Submitting changes + + + +Push your changes to your fork of nixpkgs. + + + +Create pull request: + + + +Write the title in format (pkg-name | service): improvement. + + + +If you update the pkg, write versions from -> to. + + + + + + +Write in comment if you have tested your patch. Do not rely much on TravisCI. + + + +If you make an improvement, write about your motivation. + + + +Notify maintainers of the package. For example add to the message: cc @jagajaga @domenkozar. + + + + + +
+ +
+Hotfixing pull requests + + + +Make the appropriate changes in you branch. + + + +Don't create additional commits, do + + + +git rebase -i + + + +git push --force to your branch. + + + + + + +
+ +
+Commit policy + + + +Commits must be sufficiently tested before being merged, both for the master and staging branches. + + + +Hydra builds for master and staging should not be used as testing platform, it's a build farm for changes that have been already tested. + + + +Master should only see non-breaking commits that do not cause mass rebuilds. + + + +Staging should only see non-breaking mass-rebuild commits. That means it's not to be used for testing, and changes must have been well tested already. Read policy here. + + + +If staging is already in a broken state, please refrain from adding extra new breakages. Stabilize it for a few days, merge into master, then resume development on staging. Keep an eye on the staging evaluations here. + + + +When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people's installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from @edolstra. + + + +
+ + -- cgit 1.4.1