[fusa-qual-wg] Add Workflow Views and Graph Generator

[ZakyHermawan]

Description

• Added Mermaid graphs for three of our workflow views.
• Added a Python graph generator script that converts *.mmd files to *.png images.

Proposed Mermaid Conventions

We don't have an official styling convention for Mermaid yet, so I applied the following rules to keep things clean:

1. Separate definitions: Keep node definitions grouped together at the top.
2. Short identifiers: Use 1-2 letter node identifiers (e.g., A, B) to make the connection logic easier to read.
3. Clean edges: Edge annotations should be simple and concise to minimize visual clutter. Because they don't need styling, double quotes aren't necessary.

Note: Some styling or HTML elements might break the Mermaid file, so it is best to keep node text containing them wrapped in double quotes.

[slotosch]

Hi,
Nice graphs!
But the decision about "confidence" is twice in the graph (decision nodes)

1. "Needed?"
2. "Confidence in the tool needed?"
   The second one should be renamed to "Qualification of the tool needed?"

[petbernt]

Non-blocking directory-structure question: the current flat hierarchy mixes Mermaid sources, generated images, the rendering script, dependency metadata, and documentation in one directory.

Would it be useful to separate these concerns? For example:

workflows/
├── README.md
├── mermaid/
│   └── *.mmd
├── scripts/
│   └── graph_generator.py
├── tests/
│   └── test_graph_generator.py
└── generated/       # untracked, if retained

The exact structure is not important, but agreeing on a convention now may help keep this area manageable as more workflows and tooling are added.

[petbernt]

This question has Yes/No branches but is rendered as a process rectangle.

I think it should use curly brackets "{ }" instead of square brackets like the other questions.

[petbernt]

This outcome appears to correspond to TPL-006, which uses the term “Safety Considerations” rather than “Disclaimer”. Should the terminology be aligned here?

Also, “an formal” should be “a formal”

[petbernt]

I suggest removing this reference from the flowchart.

“See also slides 11 to 14 in AsiaLLVM 2025’s presentation” does not identify the presentation title, presenter, or provide a link, so a reader cannot reliably locate the source.

[petbernt]

In tool_usage_confidence_for_developers.mmd, the “Needed?” Yes branch goes to “Write plan of usage” and references LLVM-QUAL-TPL-002 - Tool Usage Plan.

This node performs the equivalent project-specific usage step but does not reference LLVM-QUAL-TPL-002. Since PR #48 describes the template as applicable to both tool providers and tool users, is the omission intentional?

[uwendi]

My comments here.

[uwendi]

@ZakyHermawan :

While reviewing #57, @petbernt noticed that the workflows still refer to LLVM-QUAL-TPL-003 as the Tool Evaluation Report. During the preparation of TPL-003, we settled on Tool Classification Report: evaluation by analysis is the activity, while classification is its documented result.

For consistency of the whole family of templates, could you please update the wording in tool_usage_confidence_for_developers.mmd and tool_usage_confidence_for_users.mmd? Thank you!

[ZakyHermawan]

I have address all reviews, check the last commit message for list of changes.

However, before merging this PR, I got one question, on tool_usage_confidence_for_developers.mmd, there is "Provide means for verification of appropriate usage", then it will reference to LLVM-QUAL-TPL-005, which is a template for "Safety Manual", should it be changed to "Provide Safety Manual" to match the term used in TPL, or just let it be ?

I am not sure about this, because it looks like we are forcing people to actually write a safety manual, which I suppose it is allowed to be in other form, other than safety manual. Not sure what it is, but usually standard did not force people to do things in certain way.

[slotosch]

I have address all reviews, check the last commit message for list of changes.

However, before merging this PR, I got one question, on tool_usage_confidence_for_developers.mmd, there is "Provide means for verification of appropriate usage", then it will reference to LLVM-QUAL-TPL-005, which is a template for "Safety Manual", should it be changed to "Provide Safety Manual" to match the term used in TPL, or just let it be ?

I am not sure about this, because it looks like we are forcing people to actually write a safety manual, which I suppose it is allowed to be in other form, other than safety manual. Not sure what it is, but usually standard did not force people to do things in certain way.

These are two different things

1. Safety Manual States what needs to be done
2. Safe Usage Report (at least we call it like this) is the evidence that the the Safety Manual was followed
   Typically 1. is task of tool qualifier, while 2. is task of the tool user.

[ZakyHermawan]

@slotosch thanks for the explanation, I will not change the wording (keep it as "Provide means for verification of appropriate usage"), since changing it will alter the meaning.

[ZakyHermawan]

Btw, please ignore my force push, I accidentally deleting the root README.md, when I when I tried to restore it, I to got some line endings diff problems between clrf and lf 🤣

[uwendi]

I have address all reviews, check the last commit message for list of changes.

However, before merging this PR, I got one question, on tool_usage_confidence_for_developers.mmd, there is "Provide means for verification of appropriate usage", then it will reference to LLVM-QUAL-TPL-005, which is a template for "Safety Manual", should it be changed to "Provide Safety Manual" to match the term used in TPL, or just let it be ?

I am not sure about this, because it looks like we are forcing people to actually write a safety manual, which I suppose it is allowed to be in other form, other than safety manual. Not sure what it is, but usually standard did not force people to do things in certain way.

Thank you for raising this, @ZakyHermawan. I agree with keeping the broader wording rather than changing it to “Provide Safety Manual.”

One clarification about the reference to TPL-005: the workflows and templates are informative, reusable starting points. They do not prescribe a mandatory process, document title, or document structure. A team may reuse a template as it is, adapt or combine it with existing documentation, use another title, and tailor the workflow according to its applicable standards, assurance context, and organizational or project processes.

TPL-005 is referenced here because it provides one structured way of communicating the user-facing information and verifiable conditions needed for appropriate tool usage. It does not mean that everyone must produce a separate document called a Safety Manual. The TPL-005 guide also explicitly allows the completed content to be published under another clear title and to reference existing controlled documentation instead of duplicating it.

“Provide information for appropriate and verifiable usage" would perhaps make the intended outcome slightly clearer while remaining independent of the particular document title. However, keeping the current broader wording is also acceptable.

Your question also suggests that we should explain the informative and tailorable nature of all the workflows and templates in the workflows README, so that it does not have to be inferred from each individual node.