diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 314e174cf5d2..0b0efb640e35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,30 +16,75 @@ This file contains general contributing information, but individual parts also h - [`doc`](./doc): Sources and infrastructure for the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/) - [`nixos`](./nixos): Implementation of [NixOS](https://nixos.org/manual/nixos/stable/) -## (Proposing a change) | Submitting changes +## How to propose a change -Note: contributing implies licensing those contributions -under the terms of [COPYING](COPYING), which is an MIT-like license. +This section describes in some detail how changes can be made and proposed with pull requests. + +> **Note** +> Be aware that contributing implies licensing those contributions under the terms of [COPYING](./COPYING), an MIT-like license. + +0. Set up a local version of Nixpkgs to work with using GitHub and Git + 1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) the [Nixpkgs repository](https://github.com/nixos/nixpkgs/). + 1. [Clone the forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) into a local `nixpkgs` directory. + 1. [Configure the upstream Nixpkgs repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository). + +1. Create and switch to a new Git branch, ideally such that: + - The name of the branch hints at the change you'd like to implement, e.g. `update-hello`. + - The base of the branch includes the most recent changes on the `master` branch. + > **Note** + > Depending on the change you may want to use a different branch, see + + ```bash + # Make sure you have the latest changes from upstream Nixpkgs + git fetch upstream + + # Create and switch to a new branch based off the master branch in Nixpkgs + git switch --create update-hello upstream/master + ``` + + To avoid having to download and build potentially many derivations, at the expense of using a potentially outdated version, you can base the branch off a specific [Git commit](https://www.git-scm.com/docs/gitglossary#def_commit) instead: + - The commit of the latest `nixpkgs-unstable` channel, available [here](https://channels.nixos.org/nixpkgs-unstable/git-revision). + - The commit of a local Nixpkgs downloaded using [nix-channel](https://nixos.org/manual/nix/stable/command-ref/nix-channel), available using `nix-instantiate --eval --expr '(import ).trivial.revisionWithDefault null'` + - If you're using NixOS, the commit of your NixOS installation, available with `nixos-version --revision`. + + Once you have an appropriate commit you can use it instead of `upstream/master` in the above command: + ```bash + git switch --create update-hello + ``` + +2. Make the desired changes in the local Nixpkgs repository using an editor of your choice. + Make sure to: + - Adhere to both the [general code conventions](#code-conventions), and the code conventions specific to the part you're making changes to. + See the [overview section](#overview) for more specific information. + - Test the changes. + See the [overview section](#overview) for more specific information. + - If necessary, document the change. + See the [overview section](#overview) for more specific information. + +3. Commit your changes using `git commit`. + Make sure to adhere to the [commit conventions](#commit-conventions). + + Repeat the steps 2 and 3 as many times as necessary. + Advance to the next step if all the commits (viewable with `git log`) make sense together. + +4. Push your commits to your fork of Nixpkgs. + ``` + git push --set-upstream origin HEAD + ``` + + The above command will output a link that allows you to directly quickly do the next step: + ``` + remote: Create a pull request for 'update-hello' on GitHub by visiting: + remote: https://github.com/myUser/nixpkgs/pull/new/update-hello + ``` + +5. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-pull-request) from the new branch in your Nixpkgs fork to the upstream Nixpkgs repository. + Generally you should use `master` as the pull requests base branch. + See for when a different branch should be used instead. + Make sure to go through the [pull request template](#pull-request-template) in the pre-filled default description. ### Making patches {#submitting-changes-making-patches} -- Read [Manual (How to write packages for Nix)](https://nixos.org/nixpkgs/manual/). - -- Fork [the Nixpkgs repository](https://github.com/nixos/nixpkgs/) 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 - - ```ShellSession - $ nixos-version --hash - 0998212 - $ git checkout 0998212 - $ git checkout -b 'fix/pkg-name-update' - ``` - - - Please avoid working directly on the `master` branch. - - If you removed pkgs or made some major NixOS changes, write about it in the release notes for the next stable release. For example `nixos/doc/manual/release-notes/rl-2003.xml`. - Test your changes. If you work with @@ -64,10 +109,6 @@ under the terms of [COPYING](COPYING), which is an MIT-like license. ### (Creating a pull request) -- Push your changes to your fork of nixpkgs. -- Create the pull request -- Follow [the contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#submitting-changes). - When pull requests are made, our tooling automation bot, [OfBorg](https://github.com/NixOS/ofborg) will perform various checks to help ensure expression quality.