doc: release workflow

[sthaha]

No description provided.

[JoaoBraveCoding]

Small suggestion but apart from that lgtm 👍

[JoaoBraveCoding]

The image also has to be updated to reflect the changes done to the UML code.

That reminds me that we should probably have a pointer or mention on how to do that.

Afterwards I'm happy to leave the lgtm :)

[sthaha]

The image also has to be updated to reflect the changes done to the UML code.

That reminds me that we should probably have a pointer or mention on how to do that.

Afterwards I'm happy to leave the lgtm :)

Done, and also noticed that the candidate was spelt wrong.

[JoaoBraveCoding]

/lgtm

[jan--f]

Thanks this is a very nice addition. I have two somewhat general questions:

1. Should we be more explicit in the text description in the diagram and does that work for a UML diagram? Especially where users interact with the system I think it might be nice to name PRs and branches that actual people will interact with (even if those names will include the inevitable placeholders). For example step two could Open PR "release: vX.X.X" which we could then reference again in step 5 approve PR "release vX.X.X".
2. Should we generate the png in a make file step and maybe even check that it corresponds to the uml file in a CI step?

[jan--f]

Any objection against being explicit and calling this actor Release Manager?

[JoaoBraveCoding]

Not from my side, however I'm not sure how it will look in the generated image through

[sthaha]

I have changed it, does it look okay to you ?

[sthaha]

Thanks this is a very nice addition. I have two somewhat general questions:

Should we be more explicit in the text description in the diagram and does that work for a UML diagram? Especially where users interact with the system I think it might be nice to name PRs and branches that actual people will interact with (even if those names will include the inevitable placeholders).

RM imho is acceptable since it is a well know abbreviation

Update: we can use \n to add new line, "Release\n Manager" so lets use that.

For example step two could Open PR "release: vX.X.X" which we could then reference again in step 5 approve PR "release vX.X.X".

yes, this does improve readability we can say something like " Below is a workflow for releasing 1.2.3 ". I do feel giving a concrete example is better

Should we generate the png in a make file step and maybe even check that it corresponds to the uml file in a CI step?

I am not sure if we will get good ROI on that :) . This would require installation (along with maintenance of installation steps) of another tool and since we don't expect changes to happen often (once in a month) in this flow it may not be worth the effort. When it does, using the online editors to regenerate the uml is easier. - WDYT?

[jan--f]

I am not sure if we will get good ROI on that :) . This would require installation (along with maintenance of installation steps) of another tool and since we don't expect changes to happen often (once in a month) in this flow it may not be worth the effort. When it does, using the online editors to regenerate the uml is easier. - WDYT?

I still think we should be able to generate all artifacts from the repo. PlantUML is a java project so the installation is arguable quite easy (download JAR, run it). It does require java though. With online generators my concern is that these go away (and new ones appear) so that ultimately a contributor who wants to add or change something needs to jump though extra hoops.
If I'd be a user and consider contributing a fix, this would be the moment where I think "I guess this bug stays".

Maybe if PlantUML is to expensive to maintain in our tool chain, its not the right tool?

In any case I don't think this should block this PR. I could live with an issue to change or add this.

[sthaha]

In any case I don't think this should block this PR. I could live with an issue to change or add this.

Thank you :). I have set it to automatically merge on approval.

I still think we should be able to generate all artifacts from the repo. PlantUML is a java project so the installation is arguable quite easy (download JAR, run it). It does require java though. With online generators my concern is that these go away (and new ones appear) so that ultimately a contributor who wants to add or change something needs to jump though extra hoops. If I'd be a user and consider contributing a fix, this would be the moment where I think "I guess this bug stays".

Maybe if PlantUML is to expensive to maintain in our tool chain, its not the right tool?

I have a different point of view ... PlantUML is only a means to an end i.e. we need a sequence diagram. plantuml makes it "easier" to modify the sequence diagram. Say the tool I used was powerpoint or even hand drawn, would we take a similar approach to this?

[jan--f]

Say the tool I used was powerpoint or even hand drawn, would we take a similar approach to this?

I think we'd have a different discussion in this case and I'd argue strongly against any of these two options.
I just think there is value in automating the up-to-date keeping of documentation artifacts. Happy to follow up in #228 though.