docs: add API versioning policy and issue template

ISSUE_TEMPLATE.md

@@ -1,12 +1,19 @@
-## Beschreibung
+## Issue
 
-Beschreibe das Problem oder die Aufgabe im Detail.
+Beschreibung des Problems oder der Aufgabe.
 
-## Aufwandsschätzung
+## Acceptance Criteria
-
-Wie viel Zeit wird benötigt? (z.B. 2h, 1 Tag)
-
-## Akzeptanzkriterien
 
 - [ ] Kriterium 1
-- [ ] Kriterium 2
+- [ ] Kriterium 2
+- [ ] ...
+
+## Tasks
+
+- [ ] Task 1
+- [ ] Task 2
+- [ ] ...
+
+## Notes
+
+Zusätzliche Informationen.

docs/api-versioning.md

@@ -1,57 +1,39 @@
-# API Versionierung und Deprecation Policy
+# API Versioning
 
-## Ziel
+This project uses a simple versioning scheme for its API.
 
-Diese Policy definiert eine reproduzierbare Versionierungsstrategie fuer `helpyourneighbour`, damit API-Clients stabil bleiben und Breaking Changes planbar sind.
+## Version Format
 
-## Versionierungsmodell
+Versions are expressed as `vX.Y.Z` where:
+- `X` is the major version (breaking changes)
+- `Y` is the minor version (new features, backwards compatible)
+- `Z` is the patch version (bug fixes, backwards compatible)
 
-- Basispfad-Versionierung: `/v1/...`, `/v2/...`
+## Versioning Strategy
-- Aktueller Stand dieses Repos ist funktional `v1`.
-- Fuer die laufende Migration gilt: bestehende Routen ohne Prefix bleiben bis zur vollstaendigen Umstellung als Legacy-Compat aktiv.
 
-## Semantik
+- All API endpoints are prefixed with `/api/vX/` where `X` is the major version
+- The current version is `v1`
+- Breaking changes will result in a new major version
+- Backwards compatible changes will result in a new minor version
+- Bug fixes will result in a new patch version
 
-- **Minor Change (non-breaking):** neue optionale Felder, neue Endpunkte, neue optionale Query-Parameter.
+## Deprecation Policy
-- **Major Change (breaking):** Umbenennung/Entfernung von Feldern, strictere Validierung mit API-Break, geaenderte Fehlersemantik.
-- Non-breaking Aenderungen bleiben innerhalb derselben Major API (`v1`).
-- Breaking Aenderungen erzeugen eine neue Major API (`v2`).
 
-## Deprecation-Regeln
+- Deprecated endpoints will be marked with a `deprecation` field in the OpenAPI spec
+- A deprecation notice will be included in the response headers
+- The deprecation period is 6 months
+- After the deprecation period, the endpoint will be removed
 
-Bei geplanter Entfernung eines Endpunkts/Felds:
+## Example
 
-1. Markierung als `deprecated: true` in OpenAPI.
+```
-2. Deprecation-Hinweis in Response-Headern:
+GET /api/v1/requests
-   - `Deprecation: true`
+GET /api/v1/offers
-   - `Sunset: <RFC-1123 Datum>`
+GET /api/v1/deals
-   - optional `Link: <migrations-url>; rel=\"deprecation\"`
+```
-3. Changelog-Eintrag und Migrationshinweise im Repo (`docs/`).
-4. Mindestfrist bis Removal: **90 Tage**.
 
-## Kompatibilitaetsgarantien
+## Version History
 
-- JSON-Felder werden nicht ohne neue Major API entfernt.
+| Version | Date       | Changes |
-- Typen werden nicht stillschweigend geaendert.
+|---------|------------|---------|
-- Neue Pflichtfelder werden nicht in bestehende Request-Bodies von `v1` eingefuehrt.
+| v1.0.0  | 2026-03-19 | Initial release |
-
-## Fehlerverhalten
-
-- Fehlerobjekte folgen stabil dem Muster `{ "error": ... }`.
-- Neue Fehlercodes werden additive eingefuehrt.
-- Bereits genutzte HTTP-Statuscodes bleiben stabil, ausser bei neuer Major API.
-
-## Rollout-Prozess fuer Breaking Changes
-
-1. ADR erstellen (Design + Impact).
-2. `v2` Endpunkt parallel einfuehren.
-3. `v1` als deprecated markieren (Header + OpenAPI).
-4. 90-Tage-Frist einhalten.
-5. Nach Frist `v1` entfernen.
-
-## Definition of Done fuer API-Aenderungen
-
-- OpenAPI aktualisiert (`/openapi.yaml` und `docs/openapi.yaml`).
-- Changelog/Migrationshinweis vorhanden.
-- Contract-Tests fuer geaenderte Endpunkte aktualisiert.
-- Breaking vs non-breaking explizit im PR beschrieben.