awesome-kubernetes/CLAUDE.md

CLAUDE.md — Nubenetes Project Instructions for Claude Code

Git Workflow: Gitflow

This repository uses Gitflow. All agents MUST follow this branching model:

Branches

• master — Production. Only receives merges from release branches. Every merge to master gets a tag and a GitHub Release.
• develop — Integration branch. All feature branches merge here first.
• feat/* — Feature branches. Created from develop, merged back to develop via PR.
• release/vX.Y.Z — Release branches. Created from develop when ready to release, merged to both master AND back to develop.
• gh-pages — Deployment. Never touch directly.

Release Process (mandatory for all releases)

1. Create feature branch from develop: git checkout -b feat/description develop
2. Implement changes, commit, push feature branch
3. Create PR: gh pr create --base develop --head feat/description
4. Merge PR to develop: gh pr merge N --merge
5. Create release branch: git checkout -b release/vX.Y.Z develop
6. Merge release to master: git checkout master && git merge release/vX.Y.Z --no-ff
7. Tag: git tag -a vX.Y.Z -m "description"
8. Push master + tag: git push origin master && git push origin vX.Y.Z
9. Back-merge master to develop: git checkout develop && git merge master --no-ff && git push origin develop
10. Create GitHub Release: gh release create vX.Y.Z --title "..." --notes "..."

Versioning

• Current: v2.9.2
• Format: v{major}.{minor}.{patch}
• Major: breaking changes or architectural shifts
• Minor: new features (like the digest engine, new modules)
• Patch: bug fixes, config tweaks

Protected Branches

master, develop, and gh-pages are NEVER deleted. Branch cleanup runs bi-monthly for merged feature branches.

Repository Structure

Key Directories

• docs/ — V1 source (exhaustive archive, source of truth)
• v2-docs/ — V2 source (AI-curated elite portal, derived from V1)
• src/ — Python pipeline source code
• data/ — Inventory (YAML + SQL), config files, digest JSON
• scripts/ — Utility scripts (backfill, etc.)
• .github/workflows/ — CI/CD (15 workflows)

Key Config Files

• v2-mkdocs.yml — V2 MkDocs Material configuration
• mkdocs.yml — V1 MkDocs configuration
• data/inventory.yaml / data/inventory.sql — Unified inventory (18K+ entries)
• data/curation_sources.yaml — RSS feeds and X/Twitter accounts
• data/link_rules.yaml — Curation policies
• GEMINI.md — AI mandates and learning roadmap (read by Gemini agents)

Pipeline Modules

• src/v2_optimizer.py — Main rendering engine (V2VisionEngine class)
• src/news_digest.py — 26-category temporal digest with Gemini ranking
• src/enrichment.py — CNCF Landscape + GitHub activity + license detection
• src/dedup.py — URL/hash/title deduplication engine
• src/agentic_curator.py — Ingestion pipeline with AI evaluation
• src/autonomous_discovery.py — GitHub trending discovery (14 queries)
• src/gemini_utils.py — Gemini API wrapper with key rotation
• src/inventory_manager.py — Dual YAML+SQL inventory management

Build and Run

Local testing (no API keys needed)

pip install -r requirements.txt
mkdocs serve -f v2-mkdocs.yml          # Preview V2 portal
mkdocs serve -f mkdocs.yml             # Preview V1 portal

Pipeline commands

python3 -m scripts.backfill_discovered_at   # Backfill discovered_at field
python3 -m src.news_digest                   # Generate digest (needs Gemini API key)
python3 -m src.enrichment                    # CNCF + GitHub enrichment (needs GH_TOKEN)
python3 -m src.dedup                         # Dedup scan (dry-run by default)
python3 -m src.v2_optimizer --render-only    # Render V2 portal (no AI calls)

Coding Conventions

• All Python exceptions must use except Exception as e: log_event(f"[WARN] context: {str(e)[:100]}") — never bare except: pass
• Use from src.logger import log_event for logging
• Use from src.config import MADRID_TZ for timezone-aware timestamps
• Inventory fields: discovered_at (ISO), last_ai_eval (ISO), company, geo_region must be preserved during merges
• The update_inventory_entry() function preserves discovered_at — never overwrite it with new data

URL Policy: Clean URLs, No .html Suffix

Both V1 and V2 MUST use use_directory_urls: true in their mkdocs.yml. This produces clean URLs like /kubernetes/ instead of /kubernetes.html. NEVER enable the offline plugin — it forces .html suffixes on all URLs, breaking SEO and existing deep-links. This is a hard rule.

RSS/Twitter Sources

RSS feeds are limited to those that actually work (many block bots). Don't add new RSS feeds without testing. Current working feeds are defined in data/curation_sources.yaml.