forked from lix-project/lix
chore: remove incorrect maintainers/*.md documentation
Fate has something different in store for the release process,
backporting process and the general maintainer documentation.
See lix-project/lix#260.
Change-Id: I626686ff4059aee22a3ab1664b52581b2dbf6ed7
Signed-off-by: Raito Bezarius <raito@lix.systems>
This commit is contained in:
parent
4b35e6a75e
commit
93dbb698b3
|
|
@ -1,146 +0,0 @@
|
||||||
# Nix maintainers team
|
|
||||||
|
|
||||||
## Motivation
|
|
||||||
|
|
||||||
The team's main responsibility is to set a direction for the development of Nix and ensure that the code is in good shape.
|
|
||||||
|
|
||||||
We aim to achieve this by improving the contributor experience and attracting more maintainers – that is, by helping other people contributing to Nix and eventually taking responsibility – in order to scale the development process to match users' needs.
|
|
||||||
|
|
||||||
### Objectives
|
|
||||||
|
|
||||||
- It is obvious what is worthwhile to work on.
|
|
||||||
- It is easy to find the right place in the code to make a change.
|
|
||||||
- It is clear what is expected of a pull request.
|
|
||||||
- It is predictable how to get a change merged and released.
|
|
||||||
|
|
||||||
### Tasks
|
|
||||||
|
|
||||||
- Establish, communicate, and maintain a technical roadmap
|
|
||||||
- Improve documentation targeted at contributors
|
|
||||||
- Record architecture and design decisions
|
|
||||||
- Elaborate contribution guides and abide to them
|
|
||||||
- Define and assert quality criteria for contributions
|
|
||||||
- Maintain the issue tracker and triage pull requests
|
|
||||||
- Help contributors succeed with pull requests that address roadmap milestones
|
|
||||||
- Manage the release lifecycle
|
|
||||||
- Regularly publish reports on work done
|
|
||||||
- Engage with third parties in the interest of the project
|
|
||||||
- Ensure the required maintainer capacity for all of the above
|
|
||||||
|
|
||||||
## Members
|
|
||||||
|
|
||||||
- Eelco Dolstra (@edolstra) – Team lead
|
|
||||||
- Théophane Hufschmitt (@thufschmitt)
|
|
||||||
- Valentin Gagarin (@fricklerhandwerk)
|
|
||||||
- Thomas Bereknyei (@tomberek)
|
|
||||||
- Robert Hensing (@roberth)
|
|
||||||
- John Ericson (@Ericson2314)
|
|
||||||
|
|
||||||
## Meeting protocol
|
|
||||||
|
|
||||||
The team meets twice a week:
|
|
||||||
|
|
||||||
- Discussion meeting: [Fridays 13:00-14:00 CET](https://calendar.google.com/calendar/event?eid=MHNtOGVuNWtrZXNpZHR2bW1sM3QyN2ZjaGNfMjAyMjExMjVUMTIwMDAwWiBiOW81MmZvYnFqYWs4b3E4bGZraGczdDBxZ0Bn)
|
|
||||||
|
|
||||||
1. Triage issues and pull requests from the [No Status](#no-status) column (30 min)
|
|
||||||
2. Discuss issues and pull requests from the [To discuss](#to-discuss) column (30 min)
|
|
||||||
|
|
||||||
- Work meeting: [Mondays 13:00-15:00 CET](https://calendar.google.com/calendar/event?eid=NTM1MG1wNGJnOGpmOTZhYms3bTB1bnY5cWxfMjAyMjExMjFUMTIwMDAwWiBiOW81MmZvYnFqYWs4b3E4bGZraGczdDBxZ0Bn)
|
|
||||||
|
|
||||||
1. Code review on pull requests from [In review](#in-review).
|
|
||||||
2. Other chores and tasks.
|
|
||||||
|
|
||||||
Meeting notes are collected on a [collaborative scratchpad](https://pad.lassul.us/Cv7FpYx-Ri-4VjUykQOLAw), and published on Discourse under the [Nix category](https://discourse.nixos.org/c/dev/nix/50).
|
|
||||||
|
|
||||||
## Project board protocol
|
|
||||||
|
|
||||||
The team uses a [GitHub project board](https://github.com/orgs/NixOS/projects/19/views/1) for tracking its work.
|
|
||||||
|
|
||||||
Items on the board progress through the following states:
|
|
||||||
|
|
||||||
### No Status
|
|
||||||
|
|
||||||
During the discussion meeting, the team triages new items.
|
|
||||||
To be considered, issues and pull requests must have a high-level description to provide the whole team with the necessary context at a glance.
|
|
||||||
|
|
||||||
On every meeting, at least one item from each of the following categories is inspected:
|
|
||||||
|
|
||||||
1. [critical](https://github.com/NixOS/nix/labels/critical)
|
|
||||||
2. [security](https://github.com/NixOS/nix/labels/security)
|
|
||||||
3. [regression](https://github.com/NixOS/nix/labels/regression)
|
|
||||||
4. [bug](https://github.com/NixOS/nix/issues?q=is%3Aopen+label%3Abug+sort%3Areactions-%2B1-desc)
|
|
||||||
5. [tests of existing functionality](https://github.com/NixOS/nix/issues?q=is%3Aopen+label%3Atests+-label%3Afeature+sort%3Areactions-%2B1-desc)
|
|
||||||
|
|
||||||
- [oldest pull requests](https://github.com/NixOS/nix/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc)
|
|
||||||
- [most popular pull requests](https://github.com/NixOS/nix/pulls?q=is%3Apr+is%3Aopen+sort%3Areactions-%2B1-desc)
|
|
||||||
- [oldest issues](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)
|
|
||||||
- [most popular issues](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc)
|
|
||||||
|
|
||||||
Team members can also add pull requests or issues they would like the whole team to consider.
|
|
||||||
To ensure process quality and reliability, all non-trivial pull requests must be triaged before merging.
|
|
||||||
|
|
||||||
If there is disagreement on the general idea behind an issue or pull request, it is moved to [To discuss](#to-discuss).
|
|
||||||
Otherwise, the issue or pull request in questions get the label [`idea approved`](https://github.com/NixOS/nix/labels/idea%20approved).
|
|
||||||
For issues this means that an implementation is welcome and will be prioritised for review.
|
|
||||||
For pull requests this means that:
|
|
||||||
- Unfinished work is encouraged to be continued.
|
|
||||||
- A reviewer is assigned to take responsibility for getting the pull request merged.
|
|
||||||
The item is moved to the [Assigned](#assigned) column.
|
|
||||||
- If needed, the team can decide to do a collarorative review.
|
|
||||||
Then the item is moved to the [In review](#in-review) column, and review session is scheduled.
|
|
||||||
|
|
||||||
What constitutes a trivial pull request is up to maintainers' judgement.
|
|
||||||
|
|
||||||
### To discuss
|
|
||||||
|
|
||||||
Pull requests and issues that are deemed important and controversial are discussed by the team during discussion meetings.
|
|
||||||
|
|
||||||
This may be where the merit of the change itself or the implementation strategy is contested by a team member.
|
|
||||||
|
|
||||||
As a general guideline, the order of items is determined as follows:
|
|
||||||
|
|
||||||
- Prioritise pull requests over issues
|
|
||||||
|
|
||||||
Contributors who took the time to implement concrete change proposals should not wait indefinitely.
|
|
||||||
|
|
||||||
- Prioritise fixing bugs and testing over documentation, improvements or new features
|
|
||||||
|
|
||||||
The team values stability and accessibility higher than raw functionality.
|
|
||||||
|
|
||||||
- Interleave issues and PRs
|
|
||||||
|
|
||||||
This way issues without attempts at a solution get a chance to get addressed.
|
|
||||||
|
|
||||||
### In review
|
|
||||||
|
|
||||||
Pull requests in this column are reviewed together during work meetings.
|
|
||||||
This is both for spreading implementation knowledge and for establishing common values in code reviews.
|
|
||||||
|
|
||||||
When the overall direction is agreed upon, even when further changes are required, the pull request is assigned to one team member.
|
|
||||||
If significant changes are requested or reviewers cannot come to a conclusion in reasonable time, the pull request is [marked as draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft).
|
|
||||||
|
|
||||||
### Assigned
|
|
||||||
|
|
||||||
One team member is assigned to each of these pull requests.
|
|
||||||
They will communicate with the authors, and make the final approval once all remaining issues are addressed.
|
|
||||||
|
|
||||||
If more substantive issues arise, the assignee can move the pull request back to [To discuss](#to-discuss) or [In review](#in-review) to involve the team again.
|
|
||||||
|
|
||||||
### Flowchart
|
|
||||||
|
|
||||||
The process is illustrated in the following diagram:
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
flowchart TD
|
|
||||||
discuss[To discuss]
|
|
||||||
|
|
||||||
review[To review]
|
|
||||||
|
|
||||||
New --> |Disagreement on idea| discuss
|
|
||||||
New & discuss --> |Consensus on idea| review
|
|
||||||
|
|
||||||
review --> |Consensus on implementation| Assigned
|
|
||||||
|
|
||||||
Assigned --> |Implementation issues arise| review
|
|
||||||
Assigned --> |Remaining issues fixed| Merged
|
|
||||||
```
|
|
||||||
|
|
@ -1,12 +0,0 @@
|
||||||
|
|
||||||
# Backporting
|
|
||||||
|
|
||||||
To [automatically backport a pull request](https://github.com/NixOS/nix/blob/master/.github/workflows/backport.yml) to a release branch once it's merged, assign it a label of the form [`backport <branch>`](https://github.com/NixOS/nix/labels?q=backport).
|
|
||||||
|
|
||||||
Since [GitHub Actions workflows will not trigger other workflows](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow), checks on the automatic backport need to be triggered by another actor.
|
|
||||||
This is achieved by closing and reopening the backport pull request.
|
|
||||||
|
|
||||||
This specifically affects the [`installer_test`] check.
|
|
||||||
Note that it only runs after the other tests, so it may take a while to appear.
|
|
||||||
|
|
||||||
[`installer_test`]: https://github.com/NixOS/nix/blob/895dfc656a21f6252ddf48df0d1f215effa04ecb/.github/workflows/ci.yml#L70-L91
|
|
||||||
|
|
@ -1,196 +0,0 @@
|
||||||
# Nix release process
|
|
||||||
|
|
||||||
## Release artifacts
|
|
||||||
|
|
||||||
The release process is intended to create the following for each
|
|
||||||
release:
|
|
||||||
|
|
||||||
* A Git tag
|
|
||||||
|
|
||||||
* Binary tarballs in https://releases.nixos.org/?prefix=nix/
|
|
||||||
|
|
||||||
* Docker images
|
|
||||||
|
|
||||||
* Closures in https://cache.nixos.org
|
|
||||||
|
|
||||||
* (Optionally) Updated `fallback-paths.nix` in Nixpkgs
|
|
||||||
|
|
||||||
* An updated manual on https://nixos.org/manual/nix/stable/
|
|
||||||
|
|
||||||
## Creating a new release from the `master` branch
|
|
||||||
|
|
||||||
* Make sure that the [Hydra `master` jobset](https://hydra.nixos.org/jobset/nix/master) succeeds.
|
|
||||||
|
|
||||||
* In a checkout of the Nix repo, make sure you're on `master` and run
|
|
||||||
`git pull`.
|
|
||||||
|
|
||||||
* Compile the release notes by running
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git checkout -b release-notes
|
|
||||||
$ VERSION=X.YY ./maintainers/release-notes
|
|
||||||
```
|
|
||||||
|
|
||||||
where `X.YY` is *without* the patch level, e.g. `2.12` rather than ~~`2.12.0`~~.
|
|
||||||
|
|
||||||
A commit is created.
|
|
||||||
|
|
||||||
* Proof-read / edit / rearrange the release notes if needed. Breaking changes
|
|
||||||
and highlights should go to the top.
|
|
||||||
|
|
||||||
* Push.
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git push --set-upstream $REMOTE release-notes
|
|
||||||
```
|
|
||||||
|
|
||||||
* Create a PR for `release-notes`.
|
|
||||||
|
|
||||||
* Wait for the PR to be merged.
|
|
||||||
|
|
||||||
* Create a branch for the release:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git checkout master
|
|
||||||
$ git pull
|
|
||||||
$ git checkout -b $VERSION-maintenance
|
|
||||||
```
|
|
||||||
|
|
||||||
* Mark the release as official:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ sed -e 's/officialRelease = false;/officialRelease = true;/' -i flake.nix
|
|
||||||
$ sed -e '/rl-next.md/ d' -i doc/manual/src/SUMMARY.md
|
|
||||||
```
|
|
||||||
|
|
||||||
This removes the link to `rl-next.md` from the manual and sets
|
|
||||||
`officialRelease = true` in `flake.nix`.
|
|
||||||
|
|
||||||
* Commit
|
|
||||||
|
|
||||||
* Push the release branch:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git push --set-upstream origin $VERSION-maintenance
|
|
||||||
```
|
|
||||||
|
|
||||||
* Create a jobset for the release branch on Hydra as follows:
|
|
||||||
|
|
||||||
* Go to the jobset of the previous release
|
|
||||||
(e.g. https://hydra.nixos.org/jobset/nix/maintenance-2.11).
|
|
||||||
|
|
||||||
* Select `Actions -> Clone this jobset`.
|
|
||||||
|
|
||||||
* Set identifier to `maintenance-$VERSION`.
|
|
||||||
|
|
||||||
* Set description to `$VERSION release branch`.
|
|
||||||
|
|
||||||
* Set flake URL to `github:NixOS/nix/$VERSION-maintenance`.
|
|
||||||
|
|
||||||
* Hit `Create jobset`.
|
|
||||||
|
|
||||||
* Wait for the new jobset to evaluate and build. If impatient, go to
|
|
||||||
the evaluation and select `Actions -> Bump builds to front of
|
|
||||||
queue`.
|
|
||||||
|
|
||||||
* When the jobset evaluation has succeeded building, take note of the
|
|
||||||
evaluation ID (e.g. `1780832` in
|
|
||||||
`https://hydra.nixos.org/eval/1780832`).
|
|
||||||
|
|
||||||
* Tag the release and upload the release artifacts to
|
|
||||||
[`releases.nixos.org`](https://releases.nixos.org/) and [Docker Hub](https://hub.docker.com/):
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ IS_LATEST=1 ./maintainers/upload-release.pl <EVAL-ID>
|
|
||||||
```
|
|
||||||
|
|
||||||
Note: `IS_LATEST=1` causes the `latest-release` branch to be
|
|
||||||
force-updated. This is used by the `nixos.org` website to get the
|
|
||||||
[latest Nix manual](https://nixos.org/manual/nixpkgs/unstable/).
|
|
||||||
|
|
||||||
TODO: This script requires the right AWS credentials. Document.
|
|
||||||
|
|
||||||
TODO: This script currently requires a
|
|
||||||
`/home/eelco/Dev/nix-pristine`.
|
|
||||||
|
|
||||||
TODO: trigger nixos.org netlify: https://docs.netlify.com/configure-builds/build-hooks/
|
|
||||||
|
|
||||||
* Prepare for the next point release by editing `.version` to
|
|
||||||
e.g.
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ echo 2.12.1 > .version
|
|
||||||
$ git commit -a -m 'Bump version'
|
|
||||||
$ git push
|
|
||||||
```
|
|
||||||
|
|
||||||
Commit and push this to the maintenance branch.
|
|
||||||
|
|
||||||
* Bump the version of `master`:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git checkout master
|
|
||||||
$ git pull
|
|
||||||
$ NEW_VERSION=2.13.0
|
|
||||||
$ echo $NEW_VERSION > .version
|
|
||||||
$ git checkout -b bump-$NEW_VERSION
|
|
||||||
$ git commit -a -m 'Bump version'
|
|
||||||
$ git push --set-upstream origin bump-$NEW_VERSION
|
|
||||||
```
|
|
||||||
|
|
||||||
Make a pull request and auto-merge it.
|
|
||||||
|
|
||||||
* Create a milestone for the next release, move all unresolved issues
|
|
||||||
from the previous milestone, and close the previous milestone. Set
|
|
||||||
the date for the next milestone 6 weeks from now.
|
|
||||||
|
|
||||||
* Create a backport label.
|
|
||||||
|
|
||||||
* Post an [announcement on Discourse](https://discourse.nixos.org/c/announcements/8), including the contents of
|
|
||||||
`rl-$VERSION.md`.
|
|
||||||
|
|
||||||
## Creating a point release
|
|
||||||
|
|
||||||
* Checkout.
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git checkout XX.YY-maintenance
|
|
||||||
```
|
|
||||||
|
|
||||||
* Determine the next patch version.
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ export VERSION=XX.YY.ZZ
|
|
||||||
```
|
|
||||||
|
|
||||||
* Update release notes.
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ ./maintainers/release-notes
|
|
||||||
```
|
|
||||||
|
|
||||||
* Push.
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ git push
|
|
||||||
```
|
|
||||||
|
|
||||||
* Wait for the desired evaluation of the maintenance jobset to finish
|
|
||||||
building.
|
|
||||||
|
|
||||||
* Run
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ IS_LATEST=1 ./maintainers/upload-release.pl <EVAL-ID>
|
|
||||||
```
|
|
||||||
|
|
||||||
Omit `IS_LATEST=1` when creating a point release that is not on the
|
|
||||||
most recent stable branch. This prevents `nixos.org` to going back
|
|
||||||
to an older release.
|
|
||||||
|
|
||||||
* Bump the version number of the release branch as above (e.g. to
|
|
||||||
`2.12.2`).
|
|
||||||
|
|
||||||
## Recovering from mistakes
|
|
||||||
|
|
||||||
`upload-release.pl` should be idempotent. For instance a wrong `IS_LATEST` value can be fixed that way, by running the script on the actual latest release.
|
|
||||||
Loading…
Reference in a new issue