Contributing Guide¶

Dieser Guide beschreibt den Workflow, die Standards und Prozesse für Code-, Dokumentations- und Fix-Beitraege zu TCM365.

Erste Schritte¶

Voraussetzungen¶

1. Den Entwicklungs-Guide lesen und die lokale Entwicklungsumgebung einrichten
2. Sich mit den Code-Konventionen vertraut machen
3. Den Testing Guide lesen

Entwicklungs-Workflow¶

TCM365 folgt einem Standard Fork-and-Branch Workflow:

1. Repository forken (oder Feature Branch von main erstellen)
2. Feature Branch erstellen
3. Änderungen vornehmen
4. Tests schreiben
5. Commit mit Conventional Commits
6. Push und Pull Request erstellen
7. Review-Feedback adressieren
8. Nach Approval mergen

Branch-Benennung¶

Verwenden Sie beschreibende Branch-Namen mit einem Typ-Präfix:

# Feature Branch erstellen
git checkout -b feat/my-new-feature main

Commit-Nachrichten¶

Conventional Commits (Pflicht)¶

Alle Commits müssen der Conventional Commits Spezifikation folgen. Dies wird durch Projektrichtlinien erzwungen und für automatische Changelog-Generierung und Semantic Versioning verwendet.

Format¶

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types¶

Breaking Changes¶

Haengen Sie ! nach dem Type an um einen Breaking Change zu signalisieren:

feat!: redesign tenant API response format

BREAKING CHANGE: Tenant API responses now use camelCase instead of snake_case.
All API consumers must update their response parsing logic.

Beispiele¶

# Feature mit Scope
git commit -m "feat(snapshots): add bulk delete endpoint

Adds POST /api/v1/snapshots/bulk-delete for deleting multiple snapshots
in a single request. Includes validation for snapshot ownership."

# Bugfix
git commit -m "fix(drift): correct severity calculation for Zscaler resources"

# Dokumentation
git commit -m "docs(api): update endpoint reference for v2.5.0"

# Test-Ergänzung
git commit -m "test(baselines): add compliance engine unit tests for MITRE mapping"

# Chore
git commit -m "chore(deps): upgrade TypeORM to 0.3.20"

Pull Request Prozess¶

Pull Request erstellen¶

1. Branch pushen zum Remote Repository
2. Pull Request öffnen gegen den main Branch
3. PR Template ausfüllen mit:
   • Zusammenfassung der Änderungen
   • Zugehoeriges Issue oder Jira Ticket (falls zutreffend)
   • Durchgefuehrte Tests
   • Screenshots (für UI-Änderungen)

PR Titel Format¶

Folgen Sie dem gleichen Conventional Commits Format für PR Titel:

feat(snapshots): add bulk delete endpoint
fix(drift): correct severity calculation for Zscaler
docs(api): update endpoint reference

Code Review Checkliste¶

Reviewer verifizieren:

• Conventional Commits -- Alle Commit-Nachrichten folgen der Spezifikation
• Code Style -- Besteht npm run lint und npm run format
• TypeScript Strict -- Keine any Typen, korrekte Null-Behandlung
• Tests -- Neuer/geänderter Code hat zugehörige Tests
• Tests bestehen -- Alle bestehenden Tests bestehen (npm test)
• NestJS Patterns -- Korrekte Verwendung von Modulen, Services, Guards, DTOs
• Swagger Decorators -- Neue Endpoints haben @ApiOperation, @ApiResponse
• DTO Validation -- Input DTOs verwenden class-validator Decorators
• Tenant-Isolation -- Tenant-bezogene Features verwenden TenantAccessService
• Migrationen -- Neue Entities beinhalten TypeORM Migrationen
• Keine Secrets -- Keine Credentials, API Keys oder Secrets im Code
• Dokumentation -- Komplexe Features beinhalten Inline-Dokumentation

Review-Antwort¶

• Alle Review-Kommentare adressieren
• Fixes als neue Commits pushen (kein Force-Push während der Review)
• Review erneut anfordern wenn alles Feedback adressiert ist

Versionierung¶

Semantic Versioning¶

TCM365 folgt Semantic Versioning (SemVer):

Single Source of Truth¶

Die VERSION Datei im Projekt-Root ist die einzige Wahrheitsquelle für die aktuelle Version:

2.5.0

Weitere Versionsreferenzen (backend-js/package.json, frontend/package.json, CHANGELOG.md) werden atomar durch den Release-Prozess aktualisiert.

Release Workflow¶

Der Release-Prozess:

1. Aktualisiert die VERSION Datei
2. Aktualisiert backend-js/package.json und frontend/package.json
3. Aktualisiert CHANGELOG.md mit kategorisierten Änderungen seit dem letzten Release
4. Erstellt einen Git Tag (v2.6.0)
5. Erstellt eine Jira Fix Version (falls Jira Integration konfiguriert)

Entwicklungsrichtlinien¶

Empfohlen¶

• Bestehende Patterns und Konventionen in der Codebasis befolgen
• Tests für neue Features und Bugfixes schreiben
• TypeORM Repositories für Datenbankzugriff verwenden
• ConfigService für Umgebungskonfiguration verwenden
• Path Aliases verwenden (@entities/, @common/, etc.)
• Swagger Decorators an neuen Endpoints hinzufügen
• Inputs mit class-validator DTOs validieren
• TenantAccessService für tenant-bezogenen Datenzugriff verwenden
• npm test und npm run lint vor dem Commit ausführen

Vermeiden¶

• process.env direkt verwenden (stattdessen ConfigService)
• Rohe SQL Queries schreiben (stattdessen TypeORM Repositories)
• Secrets, API Keys oder Credentials committen
• Tests für kritische Features ueberspringen
• Bestehende Migrationsdateien ändern
• any Typen in TypeScript verwenden (Strict Mode erzwungen)
• Force-Push auf geteilte Branches während der Review
• Neue Tabellen für neue Vendors erstellen (stattdessen STI mit VendorTenant)

Probleme melden¶

Bug Reports¶

Folgende Informationen einschliessen:

1. TCM365 Version (VERSION Datei oder Footer prüfen)
2. Schritte zur Reproduktion des Problems
3. Erwartetes Verhalten vs. tatsaechliches Verhalten
4. Umgebung (OS, Node.js Version, Browser)
5. Relevante Logs (Backend Structured Logs, Browser Console)
6. Screenshots (für UI-Probleme)

Feature Requests¶

Beschreiben Sie:

1. Use Case -- Welches Problem löst dies?
2. Vorgeschlagene Lösung -- Wie sollte es funktionieren?
3. Betrachtete Alternativen -- Welche anderen Ansaetze existieren?
4. Auswirkung -- Welche Module oder Features sind betroffen?

Hilfe erhalten¶

• Dokumentation: Beginnen Sie mit diesem Entwicklungs-Guide und dem CLAUDE.md
• Swagger UI: API unter http://localhost:8000/api/docs erkunden
• Diagnostics: Systemgesundheit unter GET /api/v1/diagnostics prüfen
• Team: Das Entwicklungsteam für Architekturfragen kontaktieren