GitHub-Quellcode

Verknüpfe OakCore-Knoten mit Dateien oder Verzeichnissen in einem GitHub-Repository. Datei-Bindings bieten eine schreibgeschützte Vorschau, Verzeichnis-Bindings einen begrenzten Browser für ihre Inhalte. OakCore speichert Referenzmetadaten, aber keine vollständigen Quelldateien im Projekt.

Das Connection-Setup nutzt dieselbe GitHub-Repository-Verbindung wie Issues und Pull Requests.

Quellcode mit einem Knoten verknüpfen

1. Requirement oder Test öffnen.
2. In der Sidebar Info → Bindings → Source code öffnen.
3. Repository-Connection wählen.
4. Datei- oder Verzeichnisreferenz eingeben und Link source code wählen.

Akzeptierte Referenzen:

Format	Beispiel
Repository-relativer Pfad mit dem Default-Ref der Connection	src/auth/service.py
Pfad mit explizitem Ref	src/auth@develop
GitHub-Datei-URL	https://github.com/acme/widgets/blob/main/src/auth/service.py
GitHub-Verzeichnis-URL	https://github.com/acme/widgets/tree/main/src/auth

Der Pfad muss zum Repository der gewählten Connection gehören. Zeilenanker wie #L42 werden ignoriert.

Dateien und Verzeichnisse

Bei einer Datei öffnet ein Klick auf das Binding eine syntaxhervorgehobene, schreibgeschützte Vorschau. Große Vorschauen werden gekürzt; Open in GitHub zeigt die vollständige Datei.

Bei einem Verzeichnis öffnet ein Klick den Browser für die direkten Inhalte. Unterverzeichnisse können geöffnet, begrenzte Ergebnisse seitenweise geladen und Dateien direkt in GitHub geöffnet werden. Der Browser kann den gebundenen Verzeichnisbereich nicht verlassen.

OakCore speichert:

• Ressourcentyp (file oder directory)
• Repository-Pfad und Tracking-Ref
• den Commit, auf den der Ref beim letzten erfolgreichen Sync zeigte
• Git-Blob- beziehungsweise Tree-SHA
• begrenzte Vorschaumetadaten für Dateien

Sync und Aktualisierung

Der erste Snapshot wird nach dem Verknüpfen geladen. Ein Binding auf einen Branch folgt diesem Branch; beim Aktualisieren werden Commit und Blob-/Tree-Referenz neu aufgelöst. Ein Tag- oder Commit-Ref bleibt normalerweise unverändert.

GitHub-Push-Events können Bindings als veraltet markieren. Mit Refresh können veraltete, fehlgeschlagene oder gelöschte Bindings erneut geladen werden. Existiert der Pfad nicht mehr, bleibt die letzte bekannte Referenz sichtbar, bis das Binding repariert oder entfernt wird.

Quellcode-Bindings schreiben keine Kommentare oder Backlinks in das Repository. Beim Entfernen wird nur die OakCore-Verknüpfung gelöscht.

Baselines

Neue Baselines enthalten die externe Binding-Referenz. Für Quellcode sind das Pfad, Ressourcentyp, Tracking-Ref sowie der bei Baseline-Erstellung zuletzt erfolgreich aufgelöste Commit und Blob-/Tree-SHA. Quellcode und Vorschautext werden nicht in der Baseline gespeichert.

Was das Binding nicht aussagt

Ein Quellcode-Binding ist eine Traceability-Referenz. Es beweist nicht, dass der Code ein Requirement implementiert. AST- oder semantische Codeanalyse ist nicht Teil des Bindings.

Fehlerbehebung

Symptom	Prüfen
Pfad kann nicht gebunden werden	Pfad/Ref existiert und gehört zum ausgewählten Repository
GitHub verweigert Zugriff	Token hat Contents → Read
Dateivorschau fehlt	Binding ist eine Datei und der Token darf den Inhalt lesen
Verzeichnis kann nicht geöffnet werden	Binding ist ein Verzeichnis; der Zielpfad liegt unterhalb des gebundenen Verzeichnisses
Binding ist veraltet oder gelöscht	Aktualisieren und Branch, Pfad sowie Repository-Zugriff prüfen

Siehe GitHub-Repository-Verbindung → Fehlerbehebung.