github/awesome-kubernetes
1
0
Fork 0
mirror of https://github.com/nubenetes/awesome-kubernetes.git synced 2026-07-28 01:21:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: formalize V1 vs V2 architectural distinction and add comparison matrix

Browse Source
This commit is contained in:
Nubenetes Bot
2026-05-18 16:23:30 +02:00
parent 18ab7c4342
commit 91ff789dee
2 changed files with 24 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
GEMINI.md
View File

@@ -84,14 +84,13 @@ This file contains the accumulated instructions and long-term vision for the aut
- **Exhaustive Inclusion (V2)**: Unlike standard categories, V2 pages for Special Assets MUST include 100% of the ALIVE links from V1, bypassing standard impact filters.
- **AI Curation Discovery (Autonomous)**: The discovery engine MUST periodically use **Grounding/MCP** to identify new high-quality curation sources (e.g., emerging "Awesome" repos, engineering blogs) and suggest them for inclusion in `curation_sources.yaml`.
28. **Sophisticated V2 Knowledge Architecture**: The V2 Portal MUST be structured like an advanced O'Reilly technical book:
- **Deep Hierarchical Classification**: Resources MUST be organized using the `hierarchy` metadata field (a list of up to 10 strings: Area > Topic > Subtopics). This structure is mandatory for both V1 reorganization and V2 generation to ensure perfect consistency.
- **Location-Aware Automation**: Workflows MUST utilize the location metadata in the inventory (`v1_locations`, `v2_locations`) to perform surgical updates without redundant repository scans.
- **Structural Intelligence Persistence**: All agents MUST store and reuse the `hierarchy` and location metadata in the centralized inventory. This ensures zero-cost structural updates and industrial-grade scalability.
- **O'Reilly Learning Flow**: The organization must facilitate knowledge assimilation, moving from foundational theory to advanced engineering internals in a logical, ordered sequence.
- **Dynamic Indexing**: Every V2 page MUST include a Table of Contents (TOC) with clickable anchors for all technical sub-sections.
- **AI Dimension Naming**: Prioritize industry-standard terms (e.g., "AI and Artificial Intelligence" instead of internal jargon) for top-level navigation.
- **Content Extraction**: High-value sub-topics may be extracted into dedicated documents (e.g., "Microservices" content extracted from `introduction.md` into `microservices.md`) to maintain high-density focus.
28. **Sophisticated V2 Knowledge Architecture & V1 Structural Stability**: The ecosystem maintains a strict separation of architectural philosophies between editions:
- **V1 (Archive Stability)**: The V1 archive (`docs/`) prioritized human curation and historical continuity. AI agents MUST NOT perform aggressive structural reorganization, section rebuilding, or automated TOC reconstruction in V1. Injection of new links must follow a "minimal disruption" pattern, placing resources within existing categories without altering the established manual structure.
- **V2 (O'Reilly Knowledge Flow)**: The V2 Portal (`v2-docs/`) is the innovation layer. It MUST be structured like an advanced technical book:
* **Deep Hierarchical Classification**: Resources are organized using the `hierarchy` field (Area > Topic > Subtopics). This is mandatory for V2 generation.
* **O'Reilly Learning Flow**: Organization must move from foundational theory to advanced engineering internals in a logical, ordered sequence.
* **Dynamic Indexing**: Every V2 page MUST include an automated Table of Contents (TOC) with clickable anchors for all sub-sections.
- **Location-Aware Automation**: Workflows utilize location metadata (`v1_locations`, `v2_locations`) to perform surgical updates. V1 locations are considered "Fixed Anchors," while V2 locations are "Dynamic Clusters."
29. **TOC & Structural Exceptions**: Certain files (configuration-heavy or technical tables like `mkdocs.md` or `matrix-table.md`) are exempt from TOC and deep-hierarchy requirements. These exceptions MUST be respected by all agents to avoid unnecessary structural clutter in non-navigational files as defined in [`data/link_rules.yaml`](data/link_rules.yaml).

18
README.md
View File

@@ -280,7 +280,23 @@ Nubenetes operates with two distinct editions to serve different engineering nee
- **Source of Truth:** The `v2-docs/` directory (Derived from V1).
- **Deployment:** [nubenetes.com/v2/](https://nubenetes.com/v2/)
### 5.3. The Incremental Elite Engine
### 5.3. Architecture Comparison Matrix: V1 vs. V2
To better understand the dual-nature of the project, the following matrix details the technical and philosophical differences between the two editions:
| # | Feature / Aspect | V1: Exhaustive Archive (`docs/`) | V2: Agentic Elite Portal (`v2-docs/`) |
| :--- | :--- | :--- | :--- |
| **1** | **Primary Goal** | **Historical Preservation**: Exhaustive list of all technically valid resources since 2018. | **High-Density Synthesis**: Elite selection of top-tier tools for the 2026 Architect. |
| **2** | **Structural Logic** | **Manual Stability**: Flat or semi-structured categories based on manual curation. | **Recursive Hierarchy**: Deep nesting (up to 10 levels) based on Area > Topic > Subtopics. |
| **3** | **AI Intervention** | **Minimal Disruption**: AI only injects new links into existing sections. No rebuilding. | **Total Reconstruction**: AI rebuilds pages from scratch using O'Reilly-style learning flows. |
| **4** | **Inclusion Filter** | **Low Barrier**: Any ALIVE and technically relevant link is included. | **High Maturity (MVQ)**: Minimum stars (>30) and recent activity (commits < 4 years). |
| **5** | **TOC Policy** | **Manual/Static**: Table of Contents is manually maintained or triggered on request. | **Dynamic/Automated**: Clickable TOC is automatically generated and updated in every run. |
| **6** | **Metadata Density** | **Standard**: Title, URL, and descriptive summary. | **Platinum**: Author, Reading Time, Maturity Tag, and AI-generated Professional Summary. |
| **7** | **Organization Style** | **Thematic Folders**: Organized by file name and topic sections (##). | **Strategic Dimensions**: Grouped by high-level engineering domains (e.g., Platform Engineering). |
| **8** | **Content Format** | **Original Language**: Preserves V1 native descriptions (Spanish, French, etc.). | **Global English**: All summaries and UI are in Professional English for global access. |
| **9** | **Maintenance Type** | **Surgical Repair**: Dead links are removed or updated line-by-line. | **Full Refresh**: Orphaned files are pruned and content is re-indexed from the inventory. |
| **10** | **Target Audience** | **Researchers & Historians**: Looking for specific deep technical context. | **Architects & Decision Makers**: Looking for vetted, stable, and mature solutions. |
### 5.4. The Incremental Elite Engine
To maintain the high-density quality of V2 without redundant AI costs, the `V2VisionEngine` implements an incremental synchronization strategy:
1. **Intelligent Caching**: It utilizes the centralized YAML inventory to store previous AI evaluations. Only NEW links added to V1 are sent to Gemini for classification.
2. **Dynamic "Upgrading"**: Even for cached links, the engine performs real-time local updates: