Jak kontrybuować¶
Architektura¶
Toolbox dzieli się na dwie kategorie poleceń z różnymi kontraktami.
Polecenia (commands)¶
Operacje na zewnętrznych systemach, zaprojektowane do łączenia w potoki.
- Dane wyjściowe trafiają na stdout jako NDJSON
- Wyłącznie do użycia w potokach:
logintegra youtrack issues "..." | jq . - Nie wyświetlają interaktywnych elementów UI
- Nie pytają użytkownika o potwierdzenie
Workflow¶
Gotowe scenariusze domenowe orkiestrujące wiele kroków. Działają jak TUI.
- Dane wyjściowe trafiają na stdout jako czytelny dla człowieka teskt (Rich, tabele, kolory)
- Mogą pytać użytkownika o potwierdzenie (
click.confirm,click.prompt) - Mogą wyświetlać paski postępu, spinnery itp.
- Nie są przeznaczone do pipowania
from rich.console import Console
console = Console()
console.print(f"[bold green]Release {version} created[/bold green]")
confirmed = click.confirm("Assign issues to release?")
Logi¶
Niezależnie od kategorii, logi diagnostyczne zawsze trafiają na stderr - nigdy na stdout. Dzięki temu nie zakłócają strumienia danych przy pipowaniu.
import logging
logger = logging.getLogger(__name__)
logger.info("Found %d issues", len(results)) # widoczne domyślnie
logger.debug("Query: %s", query) # widoczne tylko z --verbose
logger.error("Something went wrong: %s", e) # zawsze widoczne
Dodawanie nowego polecenia (command)¶
- Stwórz moduł w odpowiednim pakiecie, np.
youtrack/commands.py - Zdefiniuj grupę Click lub dodaj do istniejącej
- Używaj
emit()do wypisywania danych - Używaj
loggerdo komunikatów - Dodaj polecenie do
main.py
Dodawanie nowego workflow¶
- Stwórz logikę domenową w
workflows/<projekt>.py - Dodaj polecenie Click w
workflows/commands.py - Używaj Rich do prezentacji wyników
- Używaj
click.confirm/click.promptdo interakcji z użytkownikiem - Logikę domenową trzymaj oddzielnie od warstwy CLI (jak
apollo.pyvscommands.py)
Styl kodu¶
Kod piszemy po angielsku (nazwy zmiennych, komentarze, help stringi, komunikaty błędów).
Ostatnia zmiana: 2026-04-12 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e