VBB-Status-Web-App/CONTRIBUTING.md

🤝 Contributing Guide

Danke, dass du zu VBB Netz Status beitragen möchtest! Diese Anleitung hilft dir, loszulegen.

📋 Inhaltsverzeichnis

• Code of Conduct
• Wie kann ich beitragen?
• Entwicklungsumgebung
• Coding Standards
• Pull Request Prozess
• Bug Reports
• Feature Requests

---

🤝 Code of Conduct

Unsere Versprechen

• Respektvoller Umgang mit allen Contributors
• Konstruktive, freundliche Diskussionen
• Fokus auf das Beste für das Projekt und die Community
• Akzeptanz von konstruktiver Kritik

Unerwünschtes Verhalten

• Beleidigungen oder persönliche Angriffe
• Trolling oder provozierende Kommentare
• Veröffentlichung privater Informationen
• Unprofessionelles Verhalten

---

💡 Wie kann ich beitragen?

1. Code Contributions

• Bugfixes: Behebe bekannte Bugs aus Issues
• Features: Implementiere neue Features (nach Diskussion)
• Optimierungen: Verbessere Performance oder Code-Qualität
• Tests: Füge Tests hinzu (falls vorhanden)

2. Dokumentation

• README verbessern: Ergänze fehlende Informationen
• Code-Kommentare: Dokumentiere komplexe Funktionen
• Tutorials: Erstelle Anleitungen für Nutzer
• Übersetzungen: Hilf bei mehrsprachiger Unterstützung

3. Design

• UI/UX Verbesserungen: Optimiere Benutzeroberfläche
• Icons & Assets: Erstelle/verbessere Icons
• Responsive Design: Verbessere Mobile/Desktop Layouts
• Accessibility: Erhöhe Barrierefreiheit

4. Testing

• Bug Testing: Teste auf verschiedenen Geräten
• Browser Compatibility: Prüfe verschiedene Browser
• Performance Testing: Messe Ladezeiten & Optimierungen
• User Feedback: Sammle Rückmeldungen von Nutzern

---

🔧 Entwicklungsumgebung

Setup

1. Repository forken

   # Auf GitHub: Fork-Button klicken
   

2. Dein Fork klonen

   git clone https://github.com/DEIN_USERNAME/VBB-Status-Web-App.git
   cd VBB-Status-Web-App
   

3. Upstream Repository hinzufügen

   git remote add upstream https://github.com/Serverlele30/VBB-Status-Web-App.git
   

4. Dependencies installieren

   npm install
   

5. Development Server starten

   npm start
   

Entwicklungs-Workflow

1. Neuen Branch erstellen

   git checkout -b feature/deine-feature-beschreibung
   # oder
   git checkout -b fix/bug-beschreibung
   

2. Änderungen vornehmen

   • Editiere index.html, styles.css, script.js
   • Teste lokal: https://localhost:3000

3. Regelmäßig committen

   git add .
   git commit -m "feat: Kurze Beschreibung der Änderung"
   

4. Mit Upstream synchronisieren

   git fetch upstream
   git rebase upstream/main
   

5. Push zu deinem Fork

   git push origin feature/deine-feature-beschreibung
   

---

📝 Coding Standards

HTML

<!-- ✅ Gut: Saubere Struktur, semantisches HTML -->
<section class="departure-list" aria-label="Abfahrten">
    <article class="departure-item">
        <h3>Alexanderplatz</h3>
    </article>
</section>

<!-- ❌ Schlecht: Keine Semantik, unleserlich -->
<div class="dl"><div class="di"><div>Alexanderplatz</div></div></div>

CSS

/* ✅ Gut: BEM-ähnliche Konvention, kommentiert */
/* Departure Item Container */
.departure-item {
    padding: 15px;
    background-color: #0a0a0a;
}

.departure-item__header {
    display: flex;
    justify-content: space-between;
}

/* ❌ Schlecht: Unklar, keine Kommentare */
.di {
    padding: 15px;
}

JavaScript

// ✅ Gut: Beschreibende Namen, Kommentare, Error Handling
async function loadDepartures(stationId) {
    try {
        const response = await fetch(`${API_BASE}/stops/${stationId}/departures`);
        if (!response.ok) throw new Error('API Error');
        
        const data = await response.json();
        return data.departures;
    } catch (error) {
        console.error('Failed to load departures:', error);
        showErrorMessage('Abfahrten konnten nicht geladen werden');
        return [];
    }
}

// ❌ Schlecht: Kryptische Namen, kein Error Handling
async function ld(s) {
    const r = await fetch(`${API_BASE}/stops/${s}/departures`);
    return await r.json();
}

Commit Messages

Folge Conventional Commits:

# Format: <type>(<scope>): <subject>

# Typen:
feat:     # Neues Feature
fix:      # Bugfix
docs:     # Dokumentation
style:    # Formatierung (kein Code-Change)
refactor: # Code-Refactoring
perf:     # Performance-Verbesserung
test:     # Tests hinzufügen
chore:    # Build, Dependencies

# Beispiele:
git commit -m "feat(live-map): Add vehicle type filter"
git commit -m "fix(departures): Handle empty API response"
git commit -m "docs(readme): Update installation instructions"
git commit -m "style(css): Format departure items"
git commit -m "perf(api): Cache API responses for 30s"

---

🔀 Pull Request Prozess

1. Vorbereitung

• Code funktioniert lokal
• Keine Console Errors
• Responsive Design getestet
• Code kommentiert
• CHANGELOG.md aktualisiert (bei größeren Changes)

2. Pull Request erstellen

1. Gehe zu deinem Fork auf GitHub
2. Klicke "Pull Request" → "New Pull Request"
3. Base: Serverlele30/VBB-Status-Web-App → main
4. Compare: dein-username/VBB-Status-Web-App → dein-branch

3. PR Beschreibung

## Beschreibung
Kurze Zusammenfassung der Änderungen

## Typ der Änderung
- [ ] Bugfix
- [ ] Neues Feature
- [ ] Breaking Change
- [ ] Dokumentation

## Wie getestet?
- [ ] Chrome Desktop
- [ ] Firefox Desktop
- [ ] Safari Mobile
- [ ] Chrome Mobile

## Screenshots (falls UI-Änderungen)
[Screenshot hier einfügen]

## Checklist
- [ ] Code folgt Style Guide
- [ ] Selbst-Review durchgeführt
- [ ] Kommentare hinzugefügt
- [ ] CHANGELOG.md aktualisiert
- [ ] Keine neuen Warnings

4. Review Prozess

• Maintainer werden deinen PR prüfen
• Möglicherweise werden Änderungen angefragt
• Nach Approval: Merge in main branch
• Branch kann gelöscht werden

---

🐛 Bug Reports

Gutes Bug Report Template:

**Beschreibung des Bugs**
Kurze, klare Beschreibung was passiert.

**Reproduktion**
Schritte um den Bug zu reproduzieren:
1. Gehe zu '...'
2. Klicke auf '...'
3. Scrolle nach '...'
4. Sieh Fehler

**Erwartetes Verhalten**
Was sollte stattdessen passieren?

**Screenshots**
Falls zutreffend, füge Screenshots hinzu.

**Umgebung:**
- Browser: [z.B. Chrome 120, Firefox 121]
- OS: [z.B. Windows 11, macOS 14, iOS 17]
- App Version: [z.B. v30.0.0]
- Mobile/Desktop: [z.B. iPhone 15 Pro]

**Zusätzlicher Kontext**
Console Errors, Network Logs, etc.

Bug Issue erstellen:

1. Gehe zu: https://github.com/Serverlele30/VBB-Status-Web-App/issues
2. Klicke "New Issue"
3. Label: bug
4. Fülle Template aus

---

💡 Feature Requests

Gutes Feature Request Template:

**Problem/Motivation**
Welches Problem würde dieses Feature lösen?
Beispiel: "Es ist schwierig, Favoriten-Stationen zu speichern..."

**Vorgeschlagene Lösung**
Wie könnte das Feature implementiert werden?
Beispiel: "Ein 'Favoriten'-Button neben jeder Station..."

**Alternativen**
Welche anderen Lösungen hast du in Betracht gezogen?

**Mockups/Wireframes**
Falls vorhanden, füge Design-Ideen hinzu.

**Zusätzlicher Kontext**
Andere Apps die ähnliche Features haben, etc.

Feature Request erstellen:

1. Gehe zu Issues
2. Label: enhancement
3. Diskutiere Feature mit Maintainern
4. Nach Approval: Implementierung starten

---

🎨 Design Guidelines

Farbschema

/* Primärfarben */
--yellow: #FFED00;      /* BVG Gelb */
--black: #000000;       /* Hintergrund */
--white: #FFFFFF;       /* Text */

/* Linienfarben (BVG Standard) */
--u1: #55A823;          /* U1 Grün */
--u2: #C00000;          /* U2 Rot */
--u3: #028D4C;          /* U3 Grün */
/* ... siehe styles.css für alle Linien */

/* Graustufen */
--gray-dark: #1a1a1a;
--gray-medium: #333333;
--gray-light: #666666;

Typografie

/* Hauptschrift: DotMatrix (Retro BVG-Look) */
font-family: 'DotMatrix', 'Courier New', monospace;

/* Größen */
--text-xs: 10px;
--text-sm: 12px;
--text-base: 14px;
--text-lg: 16px;
--text-xl: 20px;
--text-2xl: 24px;
--text-3xl: 32px;

Spacing

/* 4px Base Unit */
--spacing-1: 4px;
--spacing-2: 8px;
--spacing-3: 12px;
--spacing-4: 16px;
--spacing-5: 20px;
--spacing-6: 24px;

---

🧪 Testing Checklist

Vor Pull Request:

Browser Compatibility

• Chrome (neueste Version)
• Firefox (neueste Version)
• Safari (neueste Version)
• Edge (neueste Version)

Geräte

• Desktop (1920x1080+)
• Laptop (1366x768)
• Tablet (768x1024)
• Mobile (375x667 - iPhone SE)
• Mobile (414x896 - iPhone 11)

Features

• Abfahrten laden funktioniert
• Routenplanung funktioniert
• Live-Map zeigt Fahrzeuge
• Service Worker cached korrekt
• PWA Installation funktioniert
• Offline-Modus funktioniert

Performance

• Ladezeit < 3s
• Keine Memory Leaks
• Smooth Scrolling
• Keine Layout Shifts

---

📚 Ressourcen

APIs

• VBB API: https://v6.vbb.transport.rest/api.html
• BVG Farben: Siehe getBVGLineColor() in script.js

Libraries

• Leaflet.js: https://leafletjs.com/
• Leaflet Docs: https://leafletjs.com/reference.html

Tools

• Chrome DevTools: Browser Console, Network Tab
• Lighthouse: Performance Audit
• Can I Use: Browser Compatibility Check

---

❓ Fragen?

Bei Fragen:

1. GitHub Discussions: (falls aktiviert)
2. Issues: Stelle Fragen als Issue mit Label question
3. README/Docs: Prüfe vorhandene Dokumentation

---

🎉 Danke!

Vielen Dank für dein Interesse an VBB Netz Status! Jeder Beitrag, egal wie klein, hilft das Projekt zu verbessern.

Happy Coding! 🚇🚌🚊

---

Maintainer:

• Aaron K. (@Serverlele30)
• Claude (Anthropic)

Lizenz: MIT