Life of a pull request against NixOS/nixpkgs

Development Documentation
1

Hi,

I’m trying to have a global overview of what is happening when a contributor submits a PR against NixOS/nixpkgs.

I made a UML workflow available here, do you think you could make a review and let me know what’s missing, what’s wrong?

I think such UML workflows is a very good way to explain to newcomers what is going on when they want to submit a new pull request and when they can expect their PR to be available in NixOS.

Let me know what you think,

Thanks!

7 Likes
2

Hi

cool idea! I planned to make something like this, but you made it better than what I had in mind :smiley:

I think the column “Contributor commiter” may have a few more items when looking at https://github.com/NixOS/nixpkgs/tree/master/doc/contributing , there are other branches than master :slight_smile:

1 Like
3

Hi Solene,

Yes, there are multiple branches, I’m just doing the life of a PR against master branch for the moment, I’ll see later if we should add other branches.

I created a hackmd page where we can easily edit the workflow: https://hackmd.io/8hDd_0aITK6nnGXAQOL3_w feel free to edit it :slight_smile:

Thanks!

4

There should probably be a loop of “reviewers review PR, reviewers request changes, author makes changes, reviewers review PR” before the PR is (potentially) approved.

1 Like
5

Definitely, I might add it tomorrow, but feel free to edit in here: https://hackmd.io/8hDd_0aITK6nnGXAQOL3_w

Thanks!

1 Like
6

This is just awesome and I consider such things (graphics, contributor guidance) a priority for documentation.

Unless there are strong reasons against this, it should immediately become a PR so we have more contributor eyes on it and a structured review process.

Right now we don’t seem to have mermaid rendering for Nixpkgs/NixOS manual, but we can still discuss this based on GitHub previews and decide later how to present the result. (Worst case just check in a static SVG and leave the source in a separate file, together with notes how to manually update.)

PS: I get 403 Forbidden on the document.

3 Likes
7

Thanks !

I can submit this in a PR tomorrow.

8

I just updated the hackmd page permissions, it should be ok now.

9

And this should also include “rebasing and squashing”, as “adding commits” is usually not what happens.

10

I created a temporary repository so we can all contribute: GitHub - drupol/nixos-processes

3 Likes
11

Dear all,

I added another diagram which is almost done.

Do you have ideas of other diagrams to add in this repo?

3 Likes
12

@drupol absolutely great job on the diagrams. They are incredibly helpful. I’ve been thinking these days how we could get them to the manuals as soon as possible.

Since you’re essentially introducing a new workflow to developing Nixpkgs/NixOS, part of a PR to add the first diagram should be documentation how to maintain it. So far, we’re utterly bad at this in the Nix ecosystem, and this would be an opportunity to improve and set a good example.

I also have a few things I would like to discuss about presentation, and found myself incapable of suggesting changes directly, because I’m absolutely not used to plantUML.

Another ridiculous problem is that having a separate GitHub project prevents me to add comments or suggestions to existing code without jumping through the PR hoops.

More overviews and illustrations are key to improving user and contributor onboarding. I wrote you a DM to schedule a chat.

1 Like
13

GitHub supports mermaid diagrams embedded in markdown out of the box, so we could use that to simplify the workflow of editing / viewing them: Include diagrams in your Markdown files with Mermaid - The GitHub Blog, especially if we include them in https://github.com/NixOS/nixpkgs/blob/24ac72e8a18942e827154c334d0bc41c22bdc536/CONTRIBUTING.md.

Not sure whether our documentation markdown renderer supports that though.

1 Like
14

Sadly, support for Mindmaps and activity diagrams are not existing yet in Mermaid.