Add the labels flowchart to the README. #500

ezio-melotti · 2022-08-07T02:57:52Z

This PR adds a flowchart that describe the PR state machine to the README.

Related issues:

The flowchart will be linked in Overhaul the labels page to reflect current GH labeling practice devguide#930
The idea was brought up in Make it clear that the [awaiting ...] labels are for the bots only. devguide#868

The flowchart is described in

Lines 3 to 38 in 428290e

    
           # The following is the state machine for the flow of a PR 
        
           # (written as a DOT file; you can use Graphviz or 
        
           # http://www.webgraphviz.com/ to view the graph): 
        
           """ 
        
           digraph "PR stages" { 
        
             /* Colours represent who can make a state change or who is currently 
        
                blocking the PR from moving forward. 
        
                Blue: Anyone 
        
                Orange: PR creator 
        
                Green: Core developer 
        
                Purple: Triager Actions 
        
             */ 
        
             "New PR" [color=orange] 
        
             "Awaiting review" [shape=box, color=blue] 
        
             "Awaiting core review" [shape=box, color=green] 
        
             "Awaiting changes" [shape=box, color=orange] 
        
             "Awaiting change review" [shape=box, color=green] 
        
             "Awaiting merge" [shape=box, color=green] 
        
             "New PR" -> "Awaiting review" [label="New PR by a contributor", color=orange] 
        
             "Awaiting review" -> "Awaiting core review" [label="New review by another contributor", color=blue] 
        
             "Awaiting core review" -> "Awaiting core review" [label="New review by another contributor", color=blue] 
        
             "Awaiting core review" -> "Awaiting changes" [label="New core review requests changes", color=green] 
        
             "Awaiting changes" -> "Awaiting change review" [label="Changes are done by contributor\nBedevere requests review from core-dev", color=orange] 
        
             "Awaiting change review" -> "Awaiting changes" [label="New core review requests changes", color=green] 
        
             "Awaiting change review" -> "Awaiting merge" [label="New core review approves", color=green] 
        
             "Awaiting review" -> "Awaiting merge" [label="New core review approves", color=green] 
        
             "Awaiting review" -> "Awaiting changes" [label="New core review requests changes", color=green] 
        
             "Awaiting core review" -> "Awaiting merge" [label="New core review approves", color=green] 
        
             "New PR" -> "Awaiting core review" [label="New PR by core devs", color=green] 
        
           } 
        
           """

which renders to

For the implementation I used mermaid, which is supported natively by GitHub-flavored Markdown. The new flowchart renders to:

flowchart TD
    A([New PR]):::creator
    A -- by contributor --> B[Awaiting review]:::anyone
    A -- by core dev --> C[Awaiting core review]:::coredev
    B & C -- new review by\nanother contributor --> C
    C & B & E  -- new core review\nrequests changes --> D[Awaiting changes]:::creator
    D -- changes by contributor --> E[Awaiting change review]:::coredev
    C & E & B -- new core review\napproves ---> F[Awaiting merge]:::coredev
classDef creator stroke:#CC0;
classDef anyone stroke:#00C;
classDef coredev stroke:#0C0;
linkStyle 0,1,7 stroke:#CC0,color:auto;
linkStyle 2,3 stroke:#00C,color:auto;
linkStyle 4,5,6,8,9,10 stroke:#0C0,color:auto;

Click to see a screenshot of the flowchart (using the dark theme)

codecov · 2022-08-07T02:58:21Z

Codecov Report

Merging #500 (d85784a) into main (428290e) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##              main      #500   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           18        18           
  Lines         1829      1828    -1     
  Branches       223       223           
=========================================
- Hits          1829      1828    -1

Flag	Coverage Δ
Python_3.10	`100.00% <ø> (ø)`
Python_3.11-dev	`100.00% <ø> (ø)`
Python_3.8	`100.00% <ø> (ø)`
Python_3.9	`100.00% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
bedevere/stage.py	`100.00% <ø> (ø)`

hugovk

Should we remove the digraph from comments in stage.py and refer to this one?

DanielNoord · 2022-08-07T18:14:55Z

Could this also close #184?

ezio-melotti · 2022-08-07T20:26:39Z

Should we remove the digraph from comments in stage.py and refer to this one?

I was thinking about that 🤔
In the new graph I tried to include everything that was included in the old one, with the exception of the CSS class for triagers (since it's unused). I don't think we are losing any information by deleting it, and I can always leave a comment mentioning it in case someone needs it.

ezio-melotti · 2022-08-07T20:46:53Z

I removed the old graph and added a couple of comments.

DanielNoord · 2022-08-08T11:58:31Z

bedevere/stage.py

+# The graph replaces a previous version (written as
+# a DOT file) that was included here.
+#
+# Changes to this file should be reflected in the README.


Is this line necessary?

I'm not even sure the comments are necessary. They are probably relevant now but in 6/12 months time they will probably just become dead weight. I would be okay with removing them as well, but I'll leave that decision to you!

The one about updating the README is important to ensure the graph in the README keeps matching the code (and in turn the comment in the README ensures the devguide is updated -- assuming people see the comments).

The one about the previous version is not particularly important, but without it someone might end up wasting time looking for that graph they once saw in the code. Having a couple of extra lines for this comment is not a big cost.

Add the labels flowchart to the README.

a19f323

ezio-melotti added the enhancement label Aug 7, 2022

ezio-melotti self-assigned this Aug 7, 2022

ezio-melotti mentioned this pull request Aug 7, 2022

Make it clear that the [awaiting ...] labels are for the bots only. python/devguide#868

Closed

hugovk approved these changes Aug 7, 2022

View reviewed changes

ezio-melotti mentioned this pull request Aug 7, 2022

Improve state graph #184

Closed

ezio-melotti added 3 commits August 7, 2022 22:37

Remove old graph from stage.py.

d59c00e

Remove trailing whitespace.

262b15d

Add a comment about updating the devguide.

d85784a

ezio-melotti linked an issue Aug 7, 2022 that may be closed by this pull request

Improve state graph #184

Closed

DanielNoord approved these changes Aug 8, 2022

View reviewed changes

ezio-melotti merged commit 793bcca into main Aug 8, 2022

ezio-melotti deleted the labels-flowchart branch August 8, 2022 17:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add the labels flowchart to the README. #500

Add the labels flowchart to the README. #500

ezio-melotti commented Aug 7, 2022

codecov bot commented Aug 7, 2022 •

edited

Loading

hugovk left a comment

DanielNoord commented Aug 7, 2022

ezio-melotti commented Aug 7, 2022

ezio-melotti commented Aug 7, 2022

DanielNoord Aug 8, 2022

ezio-melotti Aug 8, 2022

	# The following is the state machine for the flow of a PR
	# (written as a DOT file; you can use Graphviz or
	# http://www.webgraphviz.com/ to view the graph):
	"""
	digraph "PR stages" {
	/* Colours represent who can make a state change or who is currently
	blocking the PR from moving forward.

	Blue: Anyone
	Orange: PR creator
	Green: Core developer
	Purple: Triager Actions
	*/

	"New PR" [color=orange]
	"Awaiting review" [shape=box, color=blue]
	"Awaiting core review" [shape=box, color=green]
	"Awaiting changes" [shape=box, color=orange]
	"Awaiting change review" [shape=box, color=green]
	"Awaiting merge" [shape=box, color=green]

	"New PR" -> "Awaiting review" [label="New PR by a contributor", color=orange]
	"Awaiting review" -> "Awaiting core review" [label="New review by another contributor", color=blue]
	"Awaiting core review" -> "Awaiting core review" [label="New review by another contributor", color=blue]
	"Awaiting core review" -> "Awaiting changes" [label="New core review requests changes", color=green]
	"Awaiting changes" -> "Awaiting change review" [label="Changes are done by contributor\nBedevere requests review from core-dev", color=orange]
	"Awaiting change review" -> "Awaiting changes" [label="New core review requests changes", color=green]
	"Awaiting change review" -> "Awaiting merge" [label="New core review approves", color=green]

	"Awaiting review" -> "Awaiting merge" [label="New core review approves", color=green]
	"Awaiting review" -> "Awaiting changes" [label="New core review requests changes", color=green]
	"Awaiting core review" -> "Awaiting merge" [label="New core review approves", color=green]

	"New PR" -> "Awaiting core review" [label="New PR by core devs", color=green]
	}
	"""

Add the labels flowchart to the README. #500

Add the labels flowchart to the README. #500

Conversation

ezio-melotti commented Aug 7, 2022

codecov bot commented Aug 7, 2022 • edited Loading

Codecov Report

hugovk left a comment

Choose a reason for hiding this comment

DanielNoord commented Aug 7, 2022

ezio-melotti commented Aug 7, 2022

ezio-melotti commented Aug 7, 2022

DanielNoord Aug 8, 2022

Choose a reason for hiding this comment

ezio-melotti Aug 8, 2022

Choose a reason for hiding this comment

codecov bot commented Aug 7, 2022 •

edited

Loading