2b20a985a5
Konvention geaendert: history/ -> docs/history/ (prompts + summary/PROJECT_CONTEXT.md). Harter Cutover im pre-commit Hook (Check 4 + Check 6 erwarten docs/history/). Bestehende Repos werden beim naechsten 'git copilot-update' automatisch per git mv migriert (Fallback mv; bei Konflikt Warnung statt Abbruch). Angepasst: pre-commit Hook, alle 6 Skripte + selftest, beide copilot-instructions.md, settings.json Session-Protokoll, history.prompt.md, README, USER/ADMIN/MAINTAINER (+ ADMIN Migrationsabschnitt). git-templates/history -> git-templates/docs/history (git mv). Validiert: shellcheck clean, fish -n clean, selftest PASS, Migrationstest PASS (sh+fish+both-present).
237 lines
8.8 KiB
Markdown
237 lines
8.8 KiB
Markdown
# Administrator-Handbuch – rd13_copilot_setup
|
||
|
||
> Zielgruppe: **Administratoren & DevOps** – Menschen, die das Setup deployen und auf Systemen verwalten.
|
||
|
||
---
|
||
|
||
## Systemvoraussetzungen
|
||
|
||
| Komponente | Anforderung |
|
||
|---|---|
|
||
| Git | ≥ 2.28 |
|
||
| Shell | POSIX sh (bash, dash) oder fish ≥ 3.x |
|
||
| VS Code / VS Code Server | beliebige aktuelle Version |
|
||
| OS | Linux oder macOS |
|
||
|
||
---
|
||
|
||
## Deployment auf einem neuen System
|
||
|
||
```bash
|
||
git clone <repo-url> ~/dotfiles/copilot-setup
|
||
cd ~/dotfiles/copilot-setup
|
||
|
||
bash scripts/deploy.sh # bash (macOS + Linux)
|
||
# oder
|
||
fish scripts/deploy.fish # fish (Linux)
|
||
```
|
||
|
||
### Was das Deploy-Skript tut
|
||
|
||
| Schritt | Was | Ziel |
|
||
|---|---|---|
|
||
| 1 | VS Code User-dir ermitteln | Server / Insiders / VSCodium / Cursor / Flatpak / macOS / Windows-WSL |
|
||
| 2 | `settings.json` deployen | `~/.vscode-server/data/User/` (oder Äquivalent) |
|
||
| 3 | Prompt Files deployen | `~/.vscode-server/data/User/prompts/` |
|
||
| 4 | Git-Templates deployen | `~/.git-templates/` inkl. Hooks, Docs, History-Template |
|
||
| 5 | Bootstrap- + Update-Skripte installieren | `~/.local/bin/` |
|
||
| 6 | Git-Aliase setzen | `~/.gitconfig` → `git init-copilot` (opt-in) + `git copilot-update` |
|
||
|
||
> **Nicht-invasiv:** `deploy.sh` setzt **kein** globales `init.templateDir` und überschreibt
|
||
> **nicht** den Standard-`git init`. Fremde `git init`/`git clone` bleiben unberührt.
|
||
> Auto-Bootstrap nur über den expliziten Alias `git init-copilot <pfad>`.
|
||
> Optional installiert `bash scripts/deploy.sh --with-self-update-hook` den
|
||
> post-merge Auto-Deploy für das Setup-Repo selbst.
|
||
|
||
---
|
||
|
||
## Git-Templates verwalten
|
||
|
||
Die Templates unter `git-templates/` werden beim Deployen nach `~/.git-templates/` kopiert.
|
||
Von dort nutzen sie `copilot-bootstrap.sh` und `git copilot-update`. Sie werden **nicht**
|
||
automatisch bei jedem `git init` kopiert (kein globales `init.templateDir` mehr) – das
|
||
geschieht nur per Opt-in: `git init-copilot <pfad>` oder `copilot-bootstrap.sh <pfad>`.
|
||
|
||
**Struktur nach Deploy:**
|
||
```
|
||
~/.git-templates/
|
||
├── .github/copilot-instructions.md
|
||
├── .vscode/settings.json
|
||
├── .vscode/extensions.json
|
||
├── hooks/
|
||
│ └── pre-commit ← Agent Quality Gate (ausführbar)
|
||
├── docs/
|
||
│ ├── USER.md
|
||
│ ├── ADMIN.md
|
||
│ └── MAINTAINER.md
|
||
└── history/
|
||
└── summary/
|
||
└── PROJECT_CONTEXT.md
|
||
```
|
||
|
||
---
|
||
|
||
## pre-commit Hook verwalten
|
||
|
||
Der Hook liegt in `git-templates/hooks/pre-commit` und wird automatisch deployed.
|
||
|
||
**Hook aktivieren in bestehenden Repos (manuell):**
|
||
```bash
|
||
cp ~/.git-templates/hooks/pre-commit /path/to/repo/.git/hooks/pre-commit
|
||
chmod +x /path/to/repo/.git/hooks/pre-commit
|
||
```
|
||
|
||
**Hook dauerhaft deaktivieren (pro Repo):**
|
||
```bash
|
||
chmod -x .git/hooks/pre-commit
|
||
```
|
||
|
||
### Quality Gate – Übersicht der Checks
|
||
|
||
| Check | Was wird geprüft | Opt-out Datei |
|
||
|---|---|---|
|
||
| 1 | Tests gestaged bei Code-Änderungen | `.copilot-no-tests` |
|
||
| 2 | Mindestens eine Zielgruppen-Doku aktualisiert | `.copilot-no-docs` |
|
||
| 3 | Alle 3 Zielgruppen-Docs vorhanden (USER/ADMIN/MAINTAINER) | – |
|
||
| 4 | `docs/history/summary/PROJECT_CONTEXT.md` aktualisiert | – |
|
||
| 5 | `docs/requirements/REQUIREMENTS.md` keine unstaged Änderungen | `.copilot-no-requirements` |
|
||
| 6 | Eine `*_session.md` ist in diesem Commit gestaged | – (kein Opt-out) |
|
||
|
||
**Opt-out Dateien** – einfach im Repo-Root anlegen um einen Check zu deaktivieren:
|
||
|
||
```bash
|
||
touch .copilot-no-tests # Repo hat kein Test-Framework
|
||
touch .copilot-no-docs # Repo hat keine Doku-Pflicht (reine Scripts/Config)
|
||
touch .copilot-no-requirements # Repo verwendet keine REQUIREMENTS.md
|
||
```
|
||
|
||
Opt-out Dateien committen damit sie für alle gelten:
|
||
```bash
|
||
git add .copilot-no-tests && git commit -m "chore: disable test check (no test framework)"
|
||
```
|
||
|
||
---
|
||
|
||
## Templates in bestehenden Repos aktualisieren (`git copilot-update`)
|
||
|
||
Nach Änderungen am Setup-Repo können alle Repos mit dem neuesten Stand versorgt werden:
|
||
|
||
```bash
|
||
cd /path/to/any-repo
|
||
git copilot-update
|
||
```
|
||
|
||
**Was `git copilot-update` tut:**
|
||
|
||
| Schritt | Was | Besonderheit |
|
||
|---|---|---|
|
||
| 0 | Setup-Quelle holen (`~/.copilot-setup/` oder `COPILOT_SETUP_DIR`) | Remote o. lokaler Klon; offline = graceful skip |
|
||
| 1b | **Script selbst aktualisieren** (`~/.local/bin/copilot-update.sh`) | startet neue Version via `exec` |
|
||
| 2 | `~/.git-templates/` aktualisieren | Hooks, Docs, History-Template |
|
||
| 3 | VS Code Prompt-Dateien aktualisieren | `~/.vscode-server/.../prompts/` |
|
||
| 4a | `.git/hooks/pre-commit` aktualisieren | nur wenn Repo vorhanden |
|
||
| 4b | `.github/copilot-instructions.md` Framework-Sektion aktualisieren | Projekt-Teil (ab `---`) bleibt unberührt |
|
||
| 4c | Fehlende `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md` anlegen | nur wenn `docs/` vorhanden + Datei fehlt; überschreibt nie |
|
||
|
||
> **Wichtig:** Die `.github/copilot-instructions.md` besteht aus zwei Teilen:
|
||
> - **Framework-Sektion** (vor `---`): Session-Protokoll, Verbotene Aktionen → wird bei jedem Update überschrieben
|
||
> - **Projekt-Sektion** (ab `---`): Stack, Architecture, Conventions → bleibt immer erhalten
|
||
|
||
---
|
||
|
||
## Setup-Quelle konfigurieren (Remote / Offline)
|
||
|
||
`git copilot-update` braucht eine Quelle. Reihenfolge: **Umgebungsvariable > Config-Datei**.
|
||
Ist nichts erreichbar, endet der Befehl **ohne Fehler** (graceful skip) – dann gibt es
|
||
schlicht nichts zu aktualisieren.
|
||
|
||
| Variable | Zweck |
|
||
|---|---|
|
||
| `COPILOT_SETUP_REMOTE_SSH` | SSH-URL des Setup-Repos |
|
||
| `COPILOT_SETUP_REMOTE_HTTP` | HTTP-URL (Fallback) |
|
||
| `COPILOT_SETUP_DIR` | Lokaler Klon/Arbeitskopie – Offline-Betrieb ohne Netz |
|
||
| `COPILOT_SETUP_CONFIG` | Alternativer Pfad zur Config-Datei |
|
||
|
||
Config-Datei (sh-Syntax) unter `~/.config/copilot-setup/config`
|
||
(bzw. `$XDG_CONFIG_HOME/copilot-setup/config`):
|
||
|
||
```sh
|
||
COPILOT_SETUP_REMOTE_SSH="ssh://git@dein-host:22/you/rd13_copilot_setup.git"
|
||
COPILOT_SETUP_REMOTE_HTTP="https://dein-host/you/rd13_copilot_setup.git"
|
||
# Alternativ rein lokal/offline:
|
||
# COPILOT_SETUP_DIR="$HOME/dotfiles/copilot-setup"
|
||
```
|
||
|
||
> Die fish-Variante **sourcet** die Datei nicht, sondern parst `KEY="value"` selbst –
|
||
> dieselbe Datei funktioniert für beide Shells.
|
||
|
||
---
|
||
|
||
## Bestehende Repos ausstatten
|
||
|
||
```bash
|
||
cd /path/to/existing-repo
|
||
copilot-bootstrap.sh
|
||
# oder von überall:
|
||
sh ~/.local/bin/copilot-bootstrap.sh /path/to/repo
|
||
```
|
||
|
||
Das Bootstrap-Skript legt idempotent an:
|
||
- `.github/copilot-instructions.md`
|
||
- `.vscode/settings.json` + `.vscode/extensions.json`
|
||
- `data/` (gitignored)
|
||
- `docs/history/prompts/` (committed) + `docs/history/summary/PROJECT_CONTEXT.md`
|
||
- `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`
|
||
- `.git/hooks/pre-commit`
|
||
- `.gitignore`-Einträge für `data/**/*`
|
||
|
||
---
|
||
|
||
## Migration: `history/` → `docs/history/`
|
||
|
||
Frühere Versionen legten die Agent-History unter `history/` im Repo-Root ab.
|
||
Neuer Standard ist `docs/history/`. Bestehende Repos werden **automatisch** migriert,
|
||
sobald dort `git copilot-update` läuft:
|
||
|
||
```bash
|
||
cd /path/to/repo
|
||
git copilot-update # erkennt history/ und verschiebt es per git mv nach docs/history/
|
||
git commit -m "chore: migrate history to docs/history"
|
||
```
|
||
|
||
- Verschiebung erfolgt mit `git mv` (Historie bleibt erhalten); Fallback `mv` für ungetrackte Dateien.
|
||
- Sind **beide** Verzeichnisse vorhanden, bricht das Tool nicht ab, sondern bittet um manuelles
|
||
Zusammenführen (`git mv history/prompts/* docs/history/prompts/ && git rm -r history`).
|
||
- Der pre-commit Hook erwartet nach der Migration ausschließlich `docs/history/`
|
||
(Check 4 + Check 6). Un-migrierte Repos müssen einmalig `git copilot-update` ausführen.
|
||
|
||
---
|
||
|
||
## `~/.local/bin/` im PATH?
|
||
|
||
Das Bootstrap-Skript wird in `~/.local/bin/` installiert. Sicherstellen dass dieser Pfad im `$PATH` ist:
|
||
|
||
**bash/zsh** (`~/.bashrc` / `~/.zshrc`):
|
||
```bash
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
```
|
||
|
||
**fish** (`~/.config/fish/config.fish`):
|
||
```fish
|
||
fish_add_path ~/.local/bin
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Problem | Ursache | Lösung |
|
||
|---|---|---|
|
||
| `copilot-bootstrap.sh: command not found` | `~/.local/bin` nicht im PATH | Siehe "PATH" oben |
|
||
| `git init-copilot` nicht gefunden | Git-Alias nicht gesetzt | `deploy.sh` erneut ausführen |
|
||
| `git copilot-update`: „Keine Setup-Quelle" | Remote nicht konfiguriert/erreichbar | `COPILOT_SETUP_REMOTE_*` oder `COPILOT_SETUP_DIR` setzen (s. Abschnitt oben) |
|
||
| Hook schlägt fehl: Tests fehlen | Code geändert ohne Tests | `/write-tests` in Copilot Chat, oder `.copilot-no-tests` anlegen |
|
||
| Hook schlägt fehl: Doku fehlt | Code geändert ohne Doku-Update | Docs aktualisieren, oder `.copilot-no-docs` anlegen |
|
||
| Hook schlägt fehl: Session fehlt | `*_session.md` nicht gestaged | Copilot Chat → `/history`, dann `git add history/` |
|
||
| Hook schlägt fehl: REQUIREMENTS.md unstaged | Requirements geändert aber nicht gestaged | `git add docs/requirements/REQUIREMENTS.md` |
|
||
| Hook nicht aktiv nach `git clone` | Hooks werden bei `clone` nicht kopiert | `copilot-bootstrap.sh` im geklonten Repo ausführen |
|