-
Notifications
You must be signed in to change notification settings - Fork 181
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve CI/CD Diagrams and Documentation #1434
Comments
Scope to "what can we do in a day's work" and "go wide than deep" per triage discussion. |
Moving to Sprint 61. |
@aj-stein-nist I'd be willing to take a crack at this, but I may need to scope it a bit. |
Let's talk about that in a minute then. :-) |
@Compton-NIST did I understand correctly that you prefer you'd like to come into this with a "fresh set of eyes" perspective and not directly work with me on the documentation piece? I am supportive of that and like that idea, if I understood you correctly. So I will unassign myself for the time being. Feel free to add me back or correct if I misunderstood. |
I am nominating @wendellpiez for review relevant code outputs and resulting process diagram, separate of AJ's reviews and others, to get a fresh perspective and dogfood these diagrams. |
I have written a script that will automatically produce a) a markdown document that outlines each workflow in a repository, and b) an svg that contains a graphical representation of each workflow, step and action. The svg also displays the relationship between workflows. This script can be run against multiple repositories. I am going to attach some of the svg files as comments under this one. We can discuss. A full zip of a run of this script that includes all markdown and graphics can be found here: https://github.com/Compton-NIST/Inspector/suites/10917151481/artifacts/551758004 |
Additional thoughts, and I'm done for a while: I've looked through the specification for workflow files to see if there are elements we could use to fully self-document within the workflow, for example, to describe a job or step, so this can be used to add context to the markdown and diagrams. The only thing I see is slightly-abusing the We should also name each step. I think many of the ones that just point to an action are missing names, so those are noted as We might also consider how we name steps so that the name provides as much context as possible to the reader. This would not require hacking the env variables, and might be sufficient. |
Agreed on the names (both wanting them and needing them to be good). Liking the approach very much. I am seeing there is lots of (irreducible?) overhead to push out even apart from the artifact productions that are wrapped in the red boxes, is that more or less what is going on here? In any case this is excellent, bravo graph dbs (perfect for something like this). |
So how are you going to finalize this work re the diagrams already committed in repos and the goals/AC? Can we discuss that during the weekly status meeting today? Thanks. |
@aj-stein-nist That sounds like a great idea. |
Work needed in sprint has been moved into the updated goals section of the issue. Work needed for follow-on sprints:
A.J. will review to the backlog for the latter list by end of week, or he shall be heckled. |
Chris and I discussed this during this week's status review meeting. AJ still has to make the follow-on work issues mentioned ☝. He is going to do so today, or else. Chris will follow on with updated works for this sprint in the AC section updated in the ticket from last week. He says still on track for completion before end of sprint/February. |
I've recommended use of an automated method to produce the diagrams and documentation of workflows to maintain parity with the actual workflows as they change across repositories. That solution currently resides here: https://github.com/Compton-NIST/Inspector
If we are good with the proposed solution: Goals
Work needed in sprint:
The Dependencies
Acceptance Criteria
|
A Sample:A full artifact can be found here: https://github.com/Compton-NIST/Inspector/suites/11232430558/artifacts/574991343 Single Workflow ExampleOverview ExampleVisual Representation of an Entire Document |
@Compton-NIST @aj-stein-nist I think an automated generation of visual documentation would be very useful! Please consider the following criteria as improvements:
|
BTW, @Compton-NIST What tool are using to generate the diagrams and flows? |
@gregelin |
Thanks for the feedback. I am trying to work this into the backlog. @gregelin, can you clarify what specifically you mean by previous version of the generated documentation? The reference information about the models or the whole website? We do have that in git in the |
@Compton-NIST re the two pending action items on for "this sprint" (Sprint 63), are we good to close this and mark as complete? Let me know or I will put it on pause to revisit in Sprint 65. Thanks for your efforts on this. |
User Story
As an OSCAL tools developer, in order to better understand the impact of the CI/CD operations, I would like to see some more clarity, consistency, and more details for CI/CD and more general workflow diagramming for the NIST OSCAL repositories.
Specifically, this is to improve #1165 and what was merged in at 3504101.
Hat tip to @gregelin for this feedback.
Goals
Clarify mixup of intent, driver (tool, script, GHA workflow name) and artifact/output for each step with grey label versus purple action boxAdd a legend to explain what the diamond, squares, labels and what they actually mean hereWork needed in sprint:
Dependencies
Acceptance Criteria
All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.The text was updated successfully, but these errors were encountered: