[Docs] Add a PlantUML activity diagram of header fixing mechanism

[emschu]

I took some time to create an activity diagram in descriptive PlantUML syntax which shows how the current header fixing mechanism works. I think this could simplify future discussions about the header fixing mechanism and its technical requirements.

My original idea was to add this to PR #40 which is merged already, therefore I create this new PR.
Feel free to refuse this PR, if the diagram or the SVG file is not desired (in this repository) or if you think this does not belong here.

[wu-sheng]

@kezhenxu94 Please check the flow, I just want to ask whether we should host svg in a source repo or website repo?

[wu-sheng]

@emschu I can't see any main repo referring this graph. Could you polish and make the structure more clear about how end-users could know this graph and read it.

[kezhenxu94]

I took some time to create an activity diagram in descriptive PlantUML syntax which shows how the current header fixing mechanism works. I think this could simplify future discussions about the header fixing mechanism and its technical requirements.

Thanks for doing this, @emschu

My original idea was to add this to PR #40 which is merged already, therefore I create this new PR.

It's better to do one thing in one PR, as #40 is complete enough on its own and this is a separate doc polish, let's continue this independently.

Feel free to refuse this PR, if the diagram or the SVG file is not desired (in this repository) or if you think this does not belong here.

The diagram is very useful for new contributors, I have some comments:

• What's the relation between the .plantuml file and .svg file, is .svg generated from .plantuml?
• Can you link to the diagram in the README.md or embed the diagram in README.md?

@wu-sheng as .plantuml / .svg is a kind of "source code" and their size is small, I think it's OK to host it here for easy maintenance, what's your opinion?

[kezhenxu94]

@emschu can you please also fix the CI, either ignore them in license checker or add licenser headers to them

[wu-sheng]

as .plantuml / .svg is a kind of "source code" and their size is small, I think it's OK to host it here for easy maintenance, what's your opinion?

It is fine to keep them once they are licensed to ASF.

[emschu]

Thank you very much for your feedback.

@kezhenxu94 Yes, the .svg can be "transpiled" from the .plantuml source file which could make it hard to maintain it.
Especially if there are more plantuml files, the .svg file generation (.png or other image types would also be possible) should be automated in my opinion.

The main Readme refers to the .svg file in a new section "Technical documentation". I hope you are fine with this.
Please let me know if you would do this in an other way.

[kezhenxu94]

Thank you very much for your feedback.

@kezhenxu94 Yes, the .svg can be "transpiled" from the .plantuml source file which could make it hard to maintain it.
Especially if there are more plantuml files, the .svg file generation (.png or other image types would also be possible) should be automated in my opinion.

Usually, if the generated files are only used at runtime, we will generate them on the fly when compiling (e.g. make command), but this case is different, we need the .svg file statically in code base for GitHub to render them in doc.

There is a risk that future contributors update .plantuml but forget to update .svg, therefore we usually have a step in CI to check the consistency between source files (.plantuml) and generated files (.svg), can you take https://github.com/apache/skywalking-cli/blob/21ba64dd2ddfd6cfeca14801e7c3888f1befc3ca/Makefile#L138-L148 as an example and add the step in this PR? Thanks in advance!

The main Readme refers to the .svg file in a new section "Technical documentation". I hope you are fine with this.

This part looks good to me.

[kezhenxu94]

Ooops, it seems that we don't support .plantuml file types yet 🤦🏻‍♂️ will you add it to make the CI pass?

[emschu]

@kezhenxu94 Thank you very much for the hint about the CI and the consistency check. I saw this check logic and I decided to remove the .svg file again as there is a public PlantUML proxy we can link to in the README while keeping only one PlantUML source file in this repository.
In addition, I don't want to introduce a JRE in the Skywalking-CI, which is required to generate PlantUML image files out of .plantuml files. I think an external web service dependency (public PlantUML proxy, see below) is also not a good idea in a CI tool, because we would have to rely on its availability and could receive "random" fails.

This is a (currently valid) PlantUML proxy link to the .plantuml file in my fork repo. The main project's Readme now contains a link to the then-valid (after merge) raw GitHub file URL (src=... part of the URL).

Doing it this way could "solve" the possible consistency problem between .svg and .plantuml files, because there are only .plantuml source files left now.

What do you think about this (temporary) solution?

[kezhenxu94]

Hi @emschu , thanks for looking into this problem.

Comparing to using the web proxy I personally think introducing a JRE in CI is more preferable, here are my reasons

• Setting up the consistency checks in CI also gives future contributors a hint about how to generate / update the .svg out of .plantuml in their local machine (they can replicate the steps in CI`
• Since the link is then-valid only after the PR is merged, consistency issue may still exist if 1) there is syntax errors in plantuml, or 2) the file name is changed, both would cause the link to be invalid.
• depending on a 3rd-party web service is not recommended in terms of Apache foundation’s perspective.

[emschu]

@kezhenxu94 Thank you for your feedback, I get your points :) I will try to integrate a JRE to generate the plantuml .svg diagram files within the next couple of days.

[kezhenxu94]

@kezhenxu94 Thank you for your feedback, I get your points :) I will try to integrate a JRE to generate the plantuml .svg diagram files within the next couple of days.

Some hints:

• https://github.com/actions/setup-java can be used to set up Java environment easily in CI.
• The plantuml.jar should be downloaded on the fly when running the consistency check, we’d better not to check a .jar file into the code base.

[wu-sheng]

@emschu Are you going to finish this?

[emschu]

@wu-sheng Yes, I plan to finish this task in this week

[emschu]

Hey @kezhenxu94, @wu-sheng,

I just finished a working integration of the plantuml <--> svg consistency check (in both directions) into this project. Please consider, that this is the first time I am working with Github actions/workflows. I did some recent tests in multiple commits to test if the new consistency check works, I hope these commits will be squashed.

I'm looking forward to get feedback about this issue from you :)

What do you think about the two new make targets and the JRE integration? Should we rely on $JAVA_HOME environment variable instead of java being available on $PATH?

[kezhenxu94]

Hey @kezhenxu94, @wu-sheng,

I just finished a working integration of the plantuml <--> svg consistency check (in both directions) into this project. Please consider, that this is the first time I am working with Github actions/workflows. I did some recent tests in multiple commits to test if the new consistency check works, I hope these commits will be squashed.

NO worry, they will be squashed when merging.

I'm looking forward to get feedback about this issue from you :)

What do you think about the two new make targets and the JRE integration? Should we rely on $JAVA_HOME environment variable instead of java being available on $PATH?

Assuming java is available on $PATH is enough for us, sometime we don't set JAVA_HOME but java is still available on $PATH.

[kezhenxu94]

Basically LGTM, just one nit

[kezhenxu94]

Thank you @emschu !!!