Improve state graph

[brettcannon]

#182 made it a bit obvious that some edge descriptions are a bit too simple to properly convey what's going on, e.g. the "New PR" edge labels don't distinguish that in one case it's for PRs from core devs and the other is for everyone else. It would probably be good to touch up the graph to make it more self-evident how things are supposed to work.

[lysnikolaou]

It might be a good idea to include an additional edge color for triager actions. Won't make too big of a difference right now, but it could come in handy in the future.

[ssd71]

I would like to work on this

[lysnikolaou]

Hey @ssd71, you can go ahead and push a PR for this, when you are ready.

[DanielNoord]

@brettcannon I'm not sure if the devguide was around when this issue was created but this information is now also stored on:
https://devguide.python.org/triage/labels/index.html

However, there isn't a flow graph there. Do we want to duplicate the information in this repository? Or do we want to move the graph over to the dev guide?

[brettcannon]

@DanielNoord I don't think the devguide page existed when I opened this issue.

As for where a graph should go, it's an interesting question. If you view it as user documentation then the devguide is the best spot. But if you view it as documentation to help maintain the code, then here is best. And there's also the concern of the devguide's version becoming outdated (although I don't think the overall flow has changed much since it's initial design).

So unfortunately I don't have a good answer.

[DanielNoord]

@brettcannon I think there is a higher chance of bevedere and its docstrings becoming outdated than that of the devguide just based on the traffic that both attract.

I'm not even sure the graph helps that much with current maintenance of the code. If something is unclear and a contributor can't discern the flow of labels from either the devguide or their descriptions on Github itself, that probably points to a lack of information there rather than an incomplete state graph.
I mean, I was able to follow most of the flow relatively easy by just looking at cpython once in a while. I don't even known this graph existed until today.

I would be okay with removing it rather than trying to cover some edge cases, but that's obviously something for you to decide!

[brettcannon]

that's obviously something for you to decide!

It's actually for @Mariatta to decide as I have stepped down from maintaining Bedevere. 😁

[hugovk]

If it is worth keeping, we could put it in Markdown in this repo and have it automatically rendered, using Mermaid:

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[ezio-melotti]

@brettcannon I'm not sure if the devguide was around when this issue was created but this information is now also stored on:
https://devguide.python.org/triage/labels/index.html

Note that this is not up-to-date and updating it is on my todo list. (see also CPython labels (view))

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

Cool! I didn't know about this.

[ezio-melotti]

As for where a graph should go, it's an interesting question.

My plan is to:

• add the graph to the README here (see Add the labels flowchart to the README. #500)
• document the labels and link to the graph in the devguide (Overhaul the labels page to reflect current GH labeling practice devguide#930)

I think readers of the devguide are more interested in the meaning of the currently applied label, rather than the full flow chart -- if they are curious they can always follow the link.

And there's also the concern of the devguide's version becoming outdated

I'll add a couple of comments to make sure that changes are reflected in both places.