Maintainer Team Changes, Merge Bot, and Committer Guidelines for Breaking Changes

When reviewing changes to a team, read the team's scope and the context around the member list for indications about the team's membership policy. In any case, request reviews from the existing team members. If the team lists no specific membership policy, feel free to merge changes to the team after giving the existing members a few days to respond. *Important:* If a team says it is a closed group, do not merge additions to the team without an approval by at least one existing member. # Maintainer scripts Various utility scripts, which are mainly useful for nixpkgs maintainers, are available under `./scripts/`. See its [README](./scripts/README.md) for further information. # nixpkgs-merge-bot To streamline autoupdates, leverage the nixpkgs-merge-bot by commenting `@NixOS/nixpkgs-merge-bot merge` if the package resides in pkgs-by-name, the commenter is among the package maintainers, and the pull request author is @r-ryantm or a Nixpkgs committer. The bot ensures that all ofborg checks, except for darwin, are successfully completed before merging the pull request. Should the checks still be underway, the bot patiently waits for ofborg to finish before attempting the merge again. # Guidelines for Committers When merging pull requests, care must be taken to reduce impact to the `master` branch. If a commit breaks evaluation, it will affect Ofborg evaluation results in other pull requests and block Hydra CI, thus introducing chaos to our workflow. One approach to avoid merging such problematic changes is to wait for successful Ofborg evaluation. Additionally, using tools like [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) can help spot issues early, before Ofborg finishes evaluation. ## Breaking changes In general breaking changes to `master` and `staging` branches are permitted, as long as they are documented in the release notes. Though restrictions might apply towards the end of a NixOS release cycle, due to our feature freeze mechanism. This is to avoid large-scale breakages shortly before and during a Zero Hydra Failures (ZHF) campaign. These restrictions also intend to decrease the likelihood of a delayed NixOS release. The feature freeze period is documented in the announcement of each release schedule. > These are some example changes and if they are considered a breaking change during a freeze period: > > - `foo: 1.2.3 -> 1.2.4`: > Assuming this package follows semantic versioning and none of its dependent packages fail to build because of this change, it can be safely merged. > Otherwise, if it can be confirmed that there is no major change in its functionality or API, but only adding new features or fixing bugs, it can also be merged. > - `unmaintained-software: drop`: > If this PR removes a leaf package or the removal doesn't otherwise break other packages, it can be merged. > - `cool-tool: rename from fancy-tool`: > As long as this PR replaces all references to the old attribute name with the new name and adds an alias, it can be merged. > - `libpopular: 4.3.2 -> 5.0.0`: > If this PR would trigger many rebuilds and/or target `staging`, it should probably be delayed until after the freeze-period is over. > Alternatively, if this PR is for a popular package and doesn't cause many rebuilds, it should also be delayed to reduce risk of breakage. > If a PR includes important changes, such as security fixes, it should be brought up to release managers. > - `nixos/transmission: refactor`: > If this PR adjusts the type, default value or effect of options in the NixOS module, so that users must rewrite their configuration to keep the current behavior unchanged, it should not be merged, as we don't have enough time to collect user feedback and avoid possible breakage. > However, it should be accepted if the current behavior is considered broken and is fixed by the PR.

This document outlines procedures for reviewing changes to maintainer teams, emphasizing that closed groups require approval from existing members. It introduces utility scripts for Nixpkgs maintainers and details how to use the `nixpkgs-merge-bot` for autoupdate merging under specific conditions, ensuring all relevant checks are completed. Furthermore, it provides guidelines for committers, stressing the importance of avoiding breaking changes to the `master` branch and recommending tools like `nixpkgs-review`. It also clarifies the policy on breaking changes, which are generally permitted if documented, but restricted during feature freeze periods before a NixOS release, providing examples of changes and their acceptability during such freezes.