PlantUML diagrams

[hjorthjort]

Description

Sequence diagrams describing different aspects of staking, and a diagram describing the dependencies of keepers (seen from the object capability model).

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

• Targeted PR against correct branch (see CONTRIBUTING.md)
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the module structure standards.
• Wrote unit and integration tests
• Updated relevant documentation (docs/) or specification (x/<module>/spec/)
• Added relevant godoc comments.
• Added a relevant changelog entry to the Unreleased section in CHANGELOG.md
• Re-reviewed Files changed in the Github PR explorer
• Review Codecov Report in the comment section below once CI passes

[amaury1093]

Could we put those diagram files under a diagrams or plantuml subfolder in their respective folders? (#8712 (comment))

[hjorthjort]

The diagrams have been moved to docs/uml. The advantage of doing that is that it simplifies the build process (over having them scattered over many different locations). I've also added the diagrams to sensible locations in the specs. I have used SVG images rather than ASCII, because I've found that the ASCII versions tend to overflow the layout of the documents. SVG becomes more compressed in the flow of the text, but should be straightforward to inspect closer.

Let me know what you think

[tac0turtle]

@AmauryM this looks good to me now. Want to take another look.

@hjorthjort is this good to merge? I see you doing extra work here and there

[tac0turtle]

oh whoops, this was premature. this broke docker builds, I will open a PR to fix it

[sahith-narahari]

oh whoops, this was premature. this broke docker builds, I will open a PR to fix it

We should make this test required imo

[tac0turtle]

oh whoops, this was premature. this broke docker builds, I will open a PR to fix it

We should make this test required imo

weird it's not.

[lovincyrus]

this broke docker builds, I will open a PR to fix it

Just noticed this PR broke the docs build on master. Are you working on a fix? @marbar3778

[toschdev]

Thanks @lovincyrus
It would be great to have the master builds of docs back. All google links or doc links in the documentation are broken and me and others regularly hit 404s.

[tac0turtle]

huh? ci is showing it builds correctly. https://github.com/cosmos/cosmos-sdk/tree/gh-pages has been pushed to, ci seems to be working. if it broke the build of the docs, then we need a way to check this. I havent stepped in the docs deployment world in a while. I can take a look tomorrow.

[tac0turtle]

@hjorthjort could you add a way to generate the plantuml? This is incorrect

[hjorthjort]

@marbar3778 Can you elaborate on "a way to generate the plantuml"? We need a plantuml binary to generate diagrams. By far the least hairy way would be to install it as a package from the standard package manager. Is it not available?

The other options are building it from source (hairier) or committing the official .jar directly, which would not stay up to date. The .jar option might be best if we can't install the package.

[hjorthjort]

Another option would be to do something like this: https://github.com/miy4/docker-plantuml/blob/master/Dockerfile

[tac0turtle]

It seems you were trying to generate the uml files for useage in docs. This was failing because there is no uml binary. Is it okay we just dont generated the uml files into something that can be rendered?

[hjorthjort]

It's also possible to just generate the files locally (by anyone who has plantuml) and we simply commit the files. Not having them in the docs at all seems like a big step back, they are there to clarify things and there seemed to be a lot of positive feedback on having them.

But it's up to you what you think is the most hygenic approach.

[tac0turtle]

we can generate them locally and push them. Could you do this? I dont see us changing these files

[hjorthjort]

okay. can you update your open PR to remove the plantuml from the Dockerfile and remove (instead of commenting out) the line for generating them.

[lovincyrus]

This should be solved by #9124 (comment)

[okwme]

Thanks @lovincyrus
It would be great to have the master builds of docs back. All google links or doc links in the documentation are broken and me and others regularly hit 404s.

bump!

[lovincyrus]

Pushed a fix here → #9124

[lovincyrus]

We should make this test required imo

#9125