lix-project/lix
20
55
Fork 31
Code Issues 344 Code Review (Gerrit) Projects 3 Releases Wiki Activity
lix/maintainers/README.md

146 lines
6.4 KiB
Markdown
Raw Normal View History

add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
# Nix maintainers team
## Motivation
incorporate feedback from maintainers
2023-02-24 14:05:31 +00:00
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.
add objectives and tasks for Nix team so far there were no even remotely measurable objectives, only a general purpose statement. this change is intended to focus the team's work on what I (and many others I talked to) perceive to be the main pain point in the development process. Co-authored-by: solene.rapenne@tweag.io
2023-01-02 10:40:09 +00:00
### 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
incorporate feedback from maintainers
2023-02-24 14:05:31 +00:00
- 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
add objectives and tasks for Nix team so far there were no even remotely measurable objectives, only a general purpose statement. this change is intended to focus the team's work on what I (and many others I talked to) perceive to be the main pain point in the development process. Co-authored-by: solene.rapenne@tweag.io
2023-01-02 10:40:09 +00:00
- Maintain the issue tracker and triage pull requests
incorporate feedback from maintainers
2023-02-24 14:05:31 +00:00
- 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
add objectives and tasks for Nix team so far there were no even remotely measurable objectives, only a general purpose statement. this change is intended to focus the team's work on what I (and many others I talked to) perceive to be the main pain point in the development process. Co-authored-by: solene.rapenne@tweag.io
2023-01-02 10:40:09 +00:00
- Ensure the required maintainer capacity for all of the above
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
## Members
- Eelco Dolstra (@edolstra) – Team lead
- Théophane Hufschmitt (@thufschmitt)
- Valentin Gagarin (@fricklerhandwerk)
- Thomas Bereknyei (@tomberek)
- Robert Hensing (@roberth)
add @Ericson2314 to the Nix team John has been part of every meeting since the beginning. He took on a lot of work on behalf of the team, and provided useful suggestions in discussions, advocating for stability, reasonable design decisions, and maintainable code. He was in general highly productive within the team process, and repeatedly helped us to keep focus on our stated goals. Specifically, early on he suggested to gather more experience with the team reviews in order derive our values for the project encode a more structured approach to guiding contributions, which is slowly bearing fruit these days. John is already the contributor with the most code changes to date (only topped by principal author Eelco), and is well-known to be highly knowledgeable about both high-level design and low-level internals of the code base. He has continued to offer high quality work during the team's operation, which resulted in many pull requests getting merged that further the team's goals. It is due time for John to be come an official team member and be granted merge access that he will surely exercise with the great care he is known for.
2023-01-11 09:00:04 +00:00
- John Ericson (@Ericson2314)
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
## Meeting protocol
The team meets twice a week:
maintainers/README.md: Use CET
2022-12-05 15:35:25 +00:00
- Discussion meeting: [Fridays 13:00-14:00 CET](https://calendar.google.com/calendar/event?eid=MHNtOGVuNWtrZXNpZHR2bW1sM3QyN2ZjaGNfMjAyMjExMjVUMTIwMDAwWiBiOW81MmZvYnFqYWs4b3E4bGZraGczdDBxZ0Bn)
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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)
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
maintainers/README.md: Use CET
2022-12-05 15:35:25 +00:00
- Work meeting: [Mondays 13:00-15:00 CET](https://calendar.google.com/calendar/event?eid=NTM1MG1wNGJnOGpmOTZhYms3bTB1bnY5cWxfMjAyMjExMjFUMTIwMDAwWiBiOW81MmZvYnFqYWs4b3E4bGZraGczdDBxZ0Bn)
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
1. Code review on pull requests from [In review](#in-review).
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
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.
review process: all PRs must be triaged in order to make the development process more transparent for everyone, all pull requests should go through the triage process before getting merged. this ensures that all team members are aware of what is going on, and that rationale for decisions is kept track of in the meeting notes for posterity. (ideally all that should go into the commit history, but this is a more invasive process change that needs further deliberation.) having all team members take at least a brief but conscious look at each change may also help with keeping our quality standards, as more reviewers are more likely to remind each other of our shared values.
2023-01-11 08:39:24 +00:00
Items on the board progress through the following states:
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
### No Status
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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.
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
On every meeting, at least one item from each of the following categories is inspected:
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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)
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
- [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)
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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.
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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.
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
What constitutes a trivial pull request is up to maintainers' judgement.
review process: all PRs must be triaged in order to make the development process more transparent for everyone, all pull requests should go through the triage process before getting merged. this ensures that all team members are aware of what is going on, and that rationale for decisions is kept track of in the meeting notes for posterity. (ideally all that should go into the commit history, but this is a more invasive process change that needs further deliberation.) having all team members take at least a brief but conscious look at each change may also help with keeping our quality standards, as more reviewers are more likely to remind each other of our shared values.
2023-01-11 08:39:24 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
### To discuss
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
Pull requests and issues that are deemed important and controversial are discussed by the team during discussion meetings.
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
This may be where the merit of the change itself or the implementation strategy is contested by a team member.
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
As a general guideline, the order of items is determined as follows:
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
- Prioritise pull requests over issues
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
Contributors who took the time to implement concrete change proposals should not wait indefinitely.
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
- Prioritise fixing bugs and testing over documentation, improvements or new features
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
The team values stability and accessibility higher than raw functionality.
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
- Interleave issues and PRs
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
This way issues without attempts at a solution get a chance to get addressed.
state priorities in triaging and discussion process based on - Nix team decisions https://discourse.nixos.org/t/2022-11-11-nix-team-meeting-minutes-7/23451#planning-discussion-1 https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731#discussion-3 - proposal to deal use labels more effectively https://discourse.nixos.org/t/improving-nix-developer-experience/21629 - documentation team decision to foster gauging interest using upvotes https://github.com/NixOS/nix/pull/7387
2022-12-08 11:01:58 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
### In review
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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.
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
When the overall direction is agreed upon, even when further changes are required, the pull request is assigned to one team member.
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
### Assigned
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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.
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
use headings instead of list items this allows easier linking and a provides a bit more visual clarity
2023-05-02 09:30:26 +00:00
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
add maintainers' handbook write down the process we have been developing and following so far. Co-Authored-By: Théophane Hufschmitt <theophane.hufschmitt@tweag.io> Co-Authored-By: John Ericson <John.Ericson@Obsidian.Systems>
2022-11-21 13:32:38 +00:00
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
```
Reference in a new issue Copy permalink