- 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, but 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 process generally works.
This section aims to document the process as we live it in Nixpkgs to set the right expectations 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, a committer needs to review and merge it.
Because committers are mostly independent, unpaid volunteers, this can take time.
It is entirely normal for your PR to sit around without any feedback for days, weeks or sometimes even months.
We strive to avoid this, but the reality is that it happens frequently.
Even when you get feedback, follow-ups may take just as long.
Don't be intimidated and kindly ask for feedback again every so often.
If your change is good, it will eventually be merged.

You can often speed up the process by understanding the committer's perspective and preparing your PR with reviewing in mind.

### The committer's perspective

PRs have varying quality and even the best people make mistakes.
Committers need to assess whether a PR's changes are good or not.
To merge, at least one committer has to be confident about its quality.

Committers typically assess three aspects:

1. Whether the change's intention is necessary and desirable.
2. Whether the code quality of your changes is good.
3. Whether the produced artifacts are good.

To get your PR merged quickly and smoothly, you should help convince committers in these aspects.

### How to help committers assess your PR

It's best to explain *why* you've made your change, because guessing the intention is not always possible.
This does not apply to trivial changes like version updates, because the intention is obvious.
For more nuanced changes or even major version upgrades, it helps if you explain the background behind your change.
For example, if you're adding a package, explain what it is and why it should be in Nixpkgs.
This goes hand in hand with [Writing good commit messages](#writing-good-commit-messages).

To show the quality of your code, you should focus on making it *reviewable*.