Skip to content

Commit d38d045

Browse files
ascerraascerra
committed
Adding visual learning guides
dir with 7 htmls meant to help people learn the infra-deployments ecosystem holistically. - A README.md describing these htmls and how to use an LLM to easily update them or create new ones. - a style-guide-for-llms.md to help in updating and creating new visual docs. - Updated the navigation.yaml to include a new section with this content in the published docs. Assisted-by: Cursor Signed-off-by: Adam Scerra <[email protected]>
1 parent 4ea4f56 commit d38d045

11 files changed

+5581
-0
lines changed

‎docs/_data/navigation.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,5 @@ docs-en:
5555
url: /docs/misc/ci-helper-app.html
5656
- title: FAQs/Troubleshooting
5757
url: /docs/misc/faq.html
58+
- title: 🎨 Visual Learning Guides
59+
url: /docs/misc/visual-learning-guides/

‎docs/misc/visual-learning-guides/README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: About Visual Learning Guides
3+
---
4+
5+
# About These Visual Guides
6+
7+
Interactive visual documentation to help understand the Konflux CI/CD platform and infra-deployments repository.
8+
9+
**→ [Browse All Visual Guides](index.html)**
10+
11+
## What Are These Guides?
12+
13+
Self-contained interactive HTML pages with:
14+
- 📊 Animated diagrams and flowcharts
15+
- 🔍 Searchable component directories
16+
- 📱 Mobile-responsive design
17+
- 🎨 Color-coded categories and difficulty levels
18+
19+
They complement the text documentation by providing visual explanations of complex workflows.
20+
21+
### How Were These Guides Created?
22+
23+
These guides were generated using **AI assistance in a Cursor workspace** that had multiple Konflux-related repositories cloned together:
24+
25+
- `redhat-appstudio/infra-deployments` - The main deployment manifests
26+
- `konflux-ci/e2e-tests` - End-to-end test suites and rules engine
27+
- `openshift/release` - OpenShift CI configuration and job definitions
28+
- `konflux-ci/architecture` - System architecture documentation
29+
- Various component repositories (build-service, integration-service, etc.)
30+
31+
**Why does this matter?** Many workflows involving infra-deployments span multiple repositories. For example:
32+
- The test selection rules that run on infra-deployments PRs are defined in `e2e-tests`
33+
- The CI job configuration lives in `openshift/release`
34+
- Component behavior that drives manifest changes is in the component repos
35+
36+
Having all these repos in the same workspace allowed the AI to research across the entire ecosystem and accurately describe how things work end-to-end, not just what's visible in infra-deployments alone.
37+
38+
**To update or create guides with full context**, clone the related repos into your workspace before asking your LLM to make changes.
39+
40+
---
41+
42+
## 🤖 Contributing with AI Assistance
43+
44+
These guides are designed to be **maintained and extended with LLM assistance** (Cursor, Copilot, Claude, etc.).
45+
46+
### Updating Existing Guides
47+
48+
When you make changes to infra-deployments that might affect a visual guide:
49+
50+
**Tell your LLM:**
51+
> "I just made changes to [describe your changes]. Check if any visual learning guides in `docs/misc/visual-learning-guides/` need to be updated. Reference the style guide in `docs/misc/visual-learning-guides/style-guide-for-llms.md` and the existing HTML files in that directory to maintain consistency."
52+
53+
**What changes trigger updates:**
54+
55+
| Your Change | Guide to Update |
56+
|-------------|-----------------|
57+
| New component in `components/` | `visual-components-map.html` |
58+
| New Kustomize overlay | `visual-kustomize-overlays.html` |
59+
| CI/testing config changes | `visual-testing-flow.html`, `visual-e2e-infra-tests.html` |
60+
| PR pairing syntax changes | `visual-pr-pairing.html` |
61+
| Renovate/MintMaker changes | `visual-renovate-workflow.html` |
62+
| Deployment pipeline/ArgoCD changes | `visual-pr-workflow.html` |
63+
64+
**Current guides:**
65+
- `index.html` - Landing page with cards linking to all guides
66+
- `visual-components-map.html` - Searchable component directory
67+
- `visual-kustomize-overlays.html` - How Kustomize overlays work
68+
- `visual-testing-flow.html` - Complete E2E testing flow
69+
- `visual-e2e-infra-tests.html` - Test selection rules for infra-deployments PRs
70+
- `visual-pr-pairing.html` - How to pair PRs across repos (Prow-specific)
71+
- `visual-pr-workflow.html` - Animated PR-to-production timeline
72+
- `visual-renovate-workflow.html` - MintMaker/Renovate automation
73+
74+
### Creating New Guides
75+
76+
To add a new visual learning guide:
77+
78+
**Tell your LLM:**
79+
> "Create a new visual learning guide about [your topic]. Read `docs/misc/visual-learning-guides/style-guide-for-llms.md` for the style guide and color palette. Use the existing HTML files in that directory as reference for structure and patterns. Research the relevant code in this repository, then generate a new HTML file following the same patterns."
80+
81+
The LLM should:
82+
1. Read `docs/misc/visual-learning-guides/style-guide-for-llms.md` for the style guide
83+
2. Read 2-3 existing HTML files in that directory to understand patterns
84+
3. Research the topic in the codebase
85+
4. Generate a new HTML file with consistent styling
86+
5. Update `docs/misc/visual-learning-guides/index.html` to add a card for the new guide
87+
88+
---
89+
90+
## 📋 Style Guide (For LLMs)
91+
92+
For detailed technical reference on colors, typography, code blocks, and patterns to use when generating or updating guides, see:
93+
94+
**→ [style-guide-for-llms.md](style-guide-for-llms.md)**
95+

‎docs/misc/visual-learning-guides/index.html‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Konflux CI/CD Visual Guide</title>
7+
<style>
8+
* {
9+
margin: 0;
10+
padding: 0;
11+
box-sizing: border-box;
12+
}
13+
14+
body {
15+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
16+
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
17+
min-height: 100vh;
18+
padding: 40px 20px;
19+
}
20+
21+
.container {
22+
max-width: 1200px;
23+
margin: 0 auto;
24+
}
25+
26+
h1 {
27+
color: white;
28+
text-align: center;
29+
font-size: 3em;
30+
margin-bottom: 20px;
31+
text-shadow: 2px 2px 4px rgba(0,0,0,0.3);
32+
}
33+
34+
.subtitle {
35+
color: rgba(255,255,255,0.9);
36+
text-align: center;
37+
font-size: 1.3em;
38+
margin-bottom: 50px;
39+
}
40+
41+
.cards-grid {
42+
display: grid;
43+
grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
44+
gap: 30px;
45+
margin-bottom: 50px;
46+
}
47+
48+
.card {
49+
background: white;
50+
border-radius: 15px;
51+
padding: 30px;
52+
box-shadow: 0 10px 30px rgba(0,0,0,0.2);
53+
transition: transform 0.3s ease, box-shadow 0.3s ease;
54+
cursor: pointer;
55+
text-decoration: none;
56+
color: inherit;
57+
display: block;
58+
}
59+
60+
.card:hover {
61+
transform: translateY(-10px);
62+
box-shadow: 0 20px 40px rgba(0,0,0,0.3);
63+
}
64+
65+
.card-icon {
66+
font-size: 3em;
67+
margin-bottom: 15px;
68+
}
69+
70+
.card h2 {
71+
color: #333;
72+
margin-bottom: 15px;
73+
font-size: 1.5em;
74+
}
75+
76+
.card p {
77+
color: #666;
78+
line-height: 1.6;
79+
margin-bottom: 15px;
80+
}
81+
82+
.card-tag {
83+
display: inline-block;
84+
background: #667eea;
85+
color: white;
86+
padding: 5px 15px;
87+
border-radius: 20px;
88+
font-size: 0.85em;
89+
margin-right: 5px;
90+
margin-top: 10px;
91+
}
92+
93+
.difficulty {
94+
display: inline-block;
95+
padding: 5px 15px;
96+
border-radius: 20px;
97+
font-size: 0.85em;
98+
margin-top: 10px;
99+
}
100+
101+
.difficulty.beginner {
102+
background: #48bb78;
103+
color: white;
104+
}
105+
106+
.difficulty.intermediate {
107+
background: #ed8936;
108+
color: white;
109+
}
110+
111+
.difficulty.advanced {
112+
background: #f56565;
113+
color: white;
114+
}
115+
116+
.footer {
117+
text-align: center;
118+
color: white;
119+
margin-top: 50px;
120+
opacity: 0.8;
121+
}
122+
123+
@media (max-width: 768px) {
124+
h1 {
125+
font-size: 2em;
126+
}
127+
128+
.cards-grid {
129+
grid-template-columns: 1fr;
130+
}
131+
}
132+
</style>
133+
</head>
134+
<body>
135+
<div class="container">
136+
<h1>🎨 Konflux CI/CD Visual Guide</h1>
137+
<p class="subtitle">Interactive diagrams and visual resources to understand the complete workflow</p>
138+
139+
<div class="cards-grid">
140+
<a href="README.html" class="card">
141+
<div class="card-icon">ℹ️</div>
142+
<h2>About & Contributing</h2>
143+
<p>Information about these visual guides, technical details, style guide, and how to contribute new guides or update existing ones.</p>
144+
<span class="difficulty beginner">All Levels</span>
145+
<span class="card-tag">Meta</span>
146+
</a>
147+
148+
<a href="visual-components-map.html" class="card">
149+
<div class="card-icon">🧩</div>
150+
<h2>Complete Components Map</h2>
151+
<p>Searchable directory of all 50+ Konflux components organized by category (Core CI/CD, Platform, Developer Tools, Infrastructure, Monitoring).</p>
152+
<span class="difficulty beginner">Beginner</span>
153+
<span class="card-tag">Searchable</span>
154+
</a>
155+
156+
<a href="visual-pr-workflow.html" class="card">
157+
<div class="card-icon">🔄</div>
158+
<h2>PR Workflow Timeline</h2>
159+
<p>Watch the complete journey of a code change from PR to production deployment with animated timeline and real timing estimates.</p>
160+
<span class="difficulty beginner">Beginner</span>
161+
<span class="card-tag">Animated</span>
162+
</a>
163+
164+
<a href="visual-testing-flow.html" class="card">
165+
<div class="card-icon">🧪</div>
166+
<h2>E2E Testing Flow</h2>
167+
<p>Explore the 4-phase testing process with real test suite names: cluster provisioning, bootstrap, test execution, and reporting with expandable details.</p>
168+
<span class="difficulty intermediate">Intermediate</span>
169+
<span class="card-tag">Expandable</span>
170+
</a>
171+
172+
<a href="visual-e2e-infra-tests.html" class="card">
173+
<div class="card-icon">🧪</div>
174+
<h2>E2E Tests for infra-deployments</h2>
175+
<p>EXACTLY what tests run when infra-deployments CI triggers. Intelligent rules engine, component-specific tests, and what each label means.</p>
176+
<span class="difficulty intermediate">Intermediate</span>
177+
<span class="card-tag">Critical</span>
178+
</a>
179+
180+
<a href="visual-renovate-workflow.html" class="card">
181+
<div class="card-icon">🤖</div>
182+
<h2>Renovate/MintMaker Workflow</h2>
183+
<p>Deep dive into HOW and WHEN MintMaker creates automated PRs in infra-deployments. Real timing, real examples, real file locations from your workspace!</p>
184+
<span class="difficulty intermediate">Intermediate</span>
185+
<span class="card-tag">Detailed</span>
186+
</a>
187+
188+
<a href="visual-pr-pairing.html" class="card">
189+
<div class="card-icon">🤝</div>
190+
<h2>PR Pairing Explained</h2>
191+
<p>Complete guide to PR pairing for breaking changes with side-by-side comparisons, real examples, and exact syntax reference.</p>
192+
<span class="difficulty intermediate">Intermediate</span>
193+
<span class="card-tag">Step-by-Step</span>
194+
</a>
195+
196+
<a href="visual-kustomize-overlays.html" class="card">
197+
<div class="card-icon">🎨</div>
198+
<h2>Understanding Kustomize Overlays</h2>
199+
<p>Complete guide to overlay patterns used throughout infra-deployments. Learn base vs overlays, when to use each, and how to structure your changes properly.</p>
200+
<span class="difficulty intermediate">Intermediate</span>
201+
<span class="card-tag">Fundamental</span>
202+
</a>
203+
</div>
204+
205+
<div class="footer">
206+
<p>💡 Tip: Start with "Components Map" if you're new, or jump to any specific topic you need!</p>
207+
<p style="margin-top: 10px; opacity: 0.6;">Konflux CI/CD Documentation • Visual Learning Resources</p>
208+
</div>
209+
</div>
210+
</body>
211+
</html>
212+

0 commit comments

Comments
 (0)