`update.nix` offers several modes for selecting packages to update, and it will execute update scripts for all matched packages that have an `updateScript` attribute.

Each update script will be passed the following environment variables:

- [`UPDATE_NIX_NAME`] – content of the `name` attribute of the updated package
- [`UPDATE_NIX_PNAME`] – content of the `pname` attribute of the updated package
- [`UPDATE_NIX_OLD_VERSION`] – content of the `version` attribute of the updated package
- [`UPDATE_NIX_ATTR_PATH`] – attribute path the `update.nix` discovered the package on (or the package's specified `attrPath` when available). Example: `pantheon.elementary-terminal`

> [!Note]
> An update script will be usually run from the root of the Nixpkgs repository, but you should not rely on that.
> Also note that `update.nix` executes update scripts in parallel by default, so you should avoid running `git commit` or any other commands that cannot handle that.

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.