Nixpkgs Commit and Code Conventions

- ✔️ Patch versions with fixes - ✔️ Minor versions with new functionality, but no breaking changes In addition, major package version updates with breaking changes are also acceptable for: - ✔️ Services that would fail without up-to-date client software, such as `spotify`, `steam`, and `discord` - ✔️ Security critical applications, such as `firefox` and `chromium` ### Changes causing mass rebuilds Which changes cause mass rebuilds is not formally defined. In order to help the decision, CI automatically assigns [`rebuild` labels](https://github.com/NixOS/nixpkgs/labels?q=rebuild) to pull requests based on the number of packages they cause rebuilds for. As a rule of thumb, if the number of rebuilds is **over 500**, it can be considered a mass rebuild. To get a sense for what changes are considered mass rebuilds, see [previously merged pull requests to the staging branches](https://github.com/NixOS/nixpkgs/issues?q=base%3Astaging+-base%3Astaging-next+is%3Amerged). ## Commit conventions - Create a commit for each logical unit. - Check for unnecessary whitespace with `git diff --check` before committing. - If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`. See [Squashing Commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) for additional information. - For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message). - When adding yourself as maintainer in the same pull request, make a separate commit with the message `maintainers: add <handle>`. Add the commit before those making changes to the package or module. See [Nixpkgs Maintainers](./maintainers/README.md) for details. - Make sure you read about any commit conventions specific to the area you're touching. See: - [Commit conventions](./pkgs/README.md#commit-conventions) for changes to `pkgs`. - [Commit conventions](./lib/README.md#commit-conventions) for changes to `lib`. - [Commit conventions](./nixos/README.md#commit-conventions) for changes to `nixos`. - [Commit conventions](./doc/README.md#commit-conventions) for changes to `doc`, the Nixpkgs manual. ### Writing good commit messages In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work. Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog. Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message. 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.

This section outlines commit and code conventions for Nixpkgs. It details the acceptability of major package version updates with breaking changes for certain services and applications. It defines 'mass rebuilds' and referencing previous merged pull requests to staging branches. Commit conventions include creating logical commits, checking whitespace, and handling maintainer additions. It emphasizes writing informative commit messages and avoiding squash merges. Code conventions cover release notes, file naming, and formatting using `nixfmt`, with instructions for local enforcement.