While update scripts should not create commits themselves, `update.nix` supports automatically creating commits when running it with `--argstr commit true`.
If you need to customize commit message, you can have the update script implement the `commit` feature.

### Supported features
[update-script-supported-features]: #supported-features

- `commit`

  This feature allows update scripts to *ask* `update.nix` to create Git commits.

  When support of this feature is declared, whenever the update script exits with `0` return status, it is expected to print a JSON list containing an object described below for each updated attribute to standard output.
  Example:

  ```json
  [
    {
      "attrPath": "volume_key",
      "oldVersion": "0.3.11",
      "newVersion": "0.3.12",
      "files": [
        "/path/to/nixpkgs/pkgs/development/libraries/volume-key/default.nix"
      ]
    }
  ]
  ```
  :::

  When `update.nix` is run with `--argstr commit true`, it will create a separate commit for each of the objects.
  An empty list can be returned when the script did not update any files; for example, when the package is already at the latest version.

  The commit object contains the following values:

  - `attrPath` – a string containing the attribute path
  - `oldVersion` – a string containing the old version
  - `newVersion` – a string containing the new version
  - `files` – a non-empty list of file paths (as strings) to add to the commit
  - `commitBody` (optional) – a string with extra content to be appended to the default commit message (useful for adding changelog links)
  - `commitMessage` (optional) – a string to use instead of the default commit message

  If the returned list contains exactly one object (e.g. `[{}]`), all values are optional and will be determined automatically.

## Reviewing contributions

### Package updates

A package update is the most trivial and common type of pull request.
These pull requests mainly consist of updating the version part of the package name and the source hash.

It can happen that non-trivial updates include patches or more complex changes.

Reviewing process:

- 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.
  - The continuous integration system 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 [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.
- Verify any change of upstream.
  - If switching from e.g. PyPi to GitHub, verify that the repo is the official one.
  - If switching to a fork, check with external sources like other package repositories for community consensus.
- Ensure any special packaging choices and required context are documented in i.e. the name of a patch or in a comment.
  - If a special version of a package is pinned, document why, so others know if/when it can be unpinned.
  - If any (especially opinionated) patch or `substituteInPlace` is applied, document why.
  - If any non-default build flags are set, document why.
  - If checks are partially or fully disabled, document why.
- Ensure that the code contains no typos.
- 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
    $ git fetch origin nixos-unstable