Standard Nazewnictwa Repozytoriów

Wszystkie repozytoria w organizacji pl.rachuna-net są organizowane w namespace’ach (katalogach). Każdy namespace ma jasno zdefiniowany cel, a repozytoria w nim zawarte podlegają spójnym regułom nazewnictwa.

---

Cel utworzenia standardu

W miarę wzrostu organizacji, liczba repozytoriów rośnie znacznie szybciej niż struktura zespołów. Bez jasnych reguł nazewnictwa organizacja szybko staje się chaotyczna:

• 🔍 Trudne wyszukiwanie - trudno znaleźć repozytorium, gdy nazwy są losowe
• 😕 Brak spójności - każdy developer wymyśla własny format nazw
• 🤝 Słaba kolaboracja - nowe osoby nie wiedzą gdzie szukać kodu
• 🚀 Problemy ze skalowaniem - CI/CD pipeline’y, automation i skripty zakładają spójne nazwy
• 📚 Dokumentacja rozmyta - trudno mapować repozytoria do dokumentacji

Korzyści ze standardu:

• Samo-dokumentujące się - nazwa od razu mówi o celu repozytorium
• Spójne - wszyscy wiedzą jak powinno się to wyglądać
• Skalowalne - łatwo dodawać nowe repozytoria bez chaosu
• Szybsze odnajdywanie - logiczna struktura ułatwia nawigację
• Łatwa automatyzacja - skrypty mogą zakładać spójne pattern’y

---

Notacja Reverse DNS

Struktura namespace’ów opiera się na koncepcji Reverse DNS Notation (odwróconej notacji DNS). Ścieżka w systemie plików bezpośrednio mapuje się na przestrzeń nazw podobnie jak w:

• Java packages (np. com.example.myapp)
• Kubernetes namespaces (np. com.rachuna-net.apps.docs)
• Konwencjach Industry Standard (Go modules, Rust crates)

Praktyczna korzyść:

Ścieżka w w gitlabie (full_path):

pl.rachuna-net/apps/docs

↓ Mapuje się na namespace:

pl.rachuna-net.apps.docs

---

Struktura Namespace’ów

Główne namespace’y organizacji:

pl.rachuna-net/
├── apps/                      # Aplikacje i serwisy webowe
├── artifacts/                 # Artefakty i komponenty wielokrotnego użytku
├── devtools/                  # Narzędzia dla deweloperów
├── flows/                     # Przepływy i procesy
├── infrastructure/            # Konfiguracja i IaC infrastruktury
├── gitlab-profile/            # Repozytorium README.md dla grupy namespace
├── platform-policies/         # Polityki i standardy platformy
├── tools/                     # Narzędzia ogólne
└── ai/                        # Projekty związane z AI

Zastosowanie

1. Wewnętrzne naming - Aplikacje mogą używać pl.rachuna-net.apps.docs jako:

   • Docker image tags: pl.rachuna-net.apps.docs:latest
   • Kubernetes namespaces: pl-rachuna-net-apps-docs
   • Package names: pl.rachuna-net.apps.docs (Java)
   • Module names: pl.rachuna-net.apps.docs (Go)

2. Wersjonowanie aplikacji - W fazie development:

   • Feature branch: pl.rachuna-net.apps.docs-feat-auth:v0.1.0-dev
   • Release candidate: pl.rachuna-net.apps.docs:v1.0.0-rc1
   • Production: pl.rachuna-net.apps.docs:v1.0.0

3. Automatyzacja - Skrypty mogą zakładać hierarchiczną strukturę:

   # Automatyczne parsowanie namespace'u
   ORG="pl.rachuna-net"
   CATEGORY="apps"
   PROJECT="docs"
   IMAGE_NAME="${ORG}.${CATEGORY}.${PROJECT}"

Dzięki temu wszystkie narzędzia (Docker, Kubernetes, CI/CD) mogą pracować z jednolitą konwencją bez dodatkowej konfiguracji.

---

Reguły Nazewnictwa

Ogólne Zasady

1. Małe litery - Wszystkie nazwy repozytoriów używają tylko małych liter
2. Kebab-case - Słowa oddzielane myślnikami (nie underscores, nie camelCase)
3. Opisowe nazwy - Nazwa powinna jasno opisywać cel repozytorium
4. Bez liczb na początek - Nazwy nie zaczynają się liczbą
5. Bez polskich znaków - Tylko ASCII (a-z, 0-9, -)

Przykłady Poprawnych Nazw

❌ Niepoprawne:

• MyApp - camelCase
• my_app - underscore
• myapp - zbyt krótkie, niejasne
• 1-app - zaczyna się liczbą
• moja-aplikacja - polskie znaki

✅ Poprawne:

• docs - czytelne, jasne
• vault-scrapper - jasny cel, kebab-case
• gitlab-ci - standard, descriptive
• k3s-gitops - descriptive, versioning