mirror of
https://github.com/nubenetes/awesome-kubernetes.git
synced 2026-07-12 09:51:00 +00:00
94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
# 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)
|
|
```bash
|
|
pip install -r requirements.txt
|
|
mkdocs serve -f v2-mkdocs.yml # Preview V2 portal
|
|
mkdocs serve -f mkdocs.yml # Preview V1 portal
|
|
```
|
|
|
|
### Pipeline commands
|
|
```bash
|
|
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`.
|