Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn't make sense as a single commit.

## Code conventions

### Release notes

If you removed packages or made some major NixOS changes, write about it in the release notes for the next stable release in [`nixos/doc/manual/release-notes`](./nixos/doc/manual/release-notes).

### File naming and organisation

Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.

### Formatting

CI [enforces](./.github/workflows/check-format.yml) all Nix files to be
formatted using the [official Nix formatter](https://github.com/NixOS/nixfmt).

You can ensure this locally using either of these commands:
```
nix-shell --run treefmt
nix develop --command treefmt
nix fmt
```

If you're starting your editor in `nix-shell` or `nix develop`,
you can also set it up to automatically format the file with `treefmt` on save.

If you have any problems with formatting, please ping the
[formatting team](https://nixos.org/community/teams/formatting/) via
[@NixOS/nix-formatting](https://github.com/orgs/NixOS/teams/nix-formatting).

### Syntax

- Set up [editorconfig](https://editorconfig.org/) for your editor, such that [the settings](./.editorconfig) are automatically applied.

- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [package naming](./pkgs/README.md#package-naming).

- Functions should list their expected arguments as precisely as possible. That is, write

  ```nix
  { stdenv, fetchurl, perl }: <...>
  ```

  instead of

  ```nix
  args: with args; <...>
  ```

  or

  ```nix
  { stdenv, fetchurl, perl, ... }: <...>
  ```

  For functions that are truly generic in the number of arguments (such as wrappers around `mkDerivation`) that have some required arguments, you should write them using an `@`-pattern:

  ```nix
  { stdenv, doCoverageAnalysis ? false, ... } @ args:

  stdenv.mkDerivation (args // {
    foo = if doCoverageAnalysis then "bla" else "";
  })
  ```

  instead of

  ```nix
  args:

  args.stdenv.mkDerivation (args // {
    foo = if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "";
  })
  ```

- Unnecessary string conversions should be avoided. Do

  ```nix
  {
    rev = version;
  }
  ```

  instead of

  ```nix
  {
    rev = "${version}";
  }
  ```

- Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.

  ```nix
  {
    buildInputs = lib.optional stdenv.hostPlatform.isDarwin iconv;
  }
  ```

  instead of

  ```nix
  {
    buildInputs = if stdenv.hostPlatform.isDarwin then [ iconv ] else null;
  }
  ```

  As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.
  If this is done a follow up pull request _should_ be created to change the code to `lib.optional(s)`.

# Practical contributing advice

To contribute effectively and efficiently, you need to be aware of how the contributing process generally works.
This section aims to document the process as we live it in Nixpkgs to set expectations right and give practical tips on how to work with it.

## I opened a PR, how do I get it merged?

In order for your PR to be merged, someone with merge permissions on the repository ("committer") needs to review and merge it.
Because the group of people with merge permissions is mostly a collection of independent unpaid volunteers who do this in their own free time, this can take some time to happen.
It is entirely normal for your PR to sit around without any feedback for days, weeks or sometimes even months.
We strive to avoid the latter cases of course but the reality of it is that this does happen quite frequently.