Danke dass du mithelfen möchtest! ❤️
Thank you for wanting to help out! The English version of this document is available here.
Dies ist ein grundlegender Überblick über den Arbeitsablauf, d.h., wie wir mit dem Code von eCamp v3 arbeiten. Weitere Informationen zur Einrichtung einer Entwicklungsumgebung auf deinem Computer findest du im Wiki. Wenn etwas bei der Einrichtung unklar ist oder du auf einen Fehler gestossen bist, gibt es einen setup-help-Kanal auf Discord, dort kannst du deine Fragen zum Setup stellen 💻
Tickets werden mit Labels gekennzeichnet und einige davon sind nicht selbsterklärend und werden hier erklärt:
- Good first issue: 💚 Anfängerfreundliche Tickets.
- Type-Labels: Zeigen an, welcher Teil der Architektur betroffen ist. Es gibt
type: Frontend,type: Print,type: Deployment&type: API. Die Architektur dafür ist teilweise im Wiki dokumentiert. - Needs prototype: 💡 Wenn du eine Idee hast, wie dieses Problem gelöst werden kann, würden wir sie gerne sehen. Dieses Problem benötigt einen Prototypen, bevor die eigentliche Implementierung beginnt, da die Spezifikationen etwas vage sind. Ein Prototyp kann vieles sein, z.B. eine Skizze, ein Mock-up oder eine Teil-Implementierung.
- Feature request: 🚀 Eine Idee/Anfrage für eine Funktionalität, die noch nicht zur Implementierung, aber zur Diskussion bereitsteht.
Auf GitHub heissen die Arbeitspakete, welche du vielleicht als Tickets kennst, Issues. Um zu starten, suche dir ein Issue aus, das dich interessiert. Wenn du neu bist, empfehlen wir, ein Good first issue auszuwählen.
Falls dir diese zu einfach sind, empfehlen wir ein Issue mit dem Label Ready for Implementation, diese sind klar spezifiziert.
Wenn du an einem Problem arbeitest, hinterlasse bitte einen Kommentar, damit wir es dir zuweisen können, um sicherzustellen, dass die Spezifikationen noch aktuell sind, und um zu verhindern, dass zwei Personen am selben Problem arbeiten.
Alternativ kannst du einen Entwurf für einen Pull-Request öffnen und die Issue-ID erwähnen, um zu signalisieren, dass du an diesem speziellen Problem arbeitest.
Bitte beachte, dass das Wiki zwar hilfreich sein kann, um das Projekt zu verstehen, aber es ist nicht vollständig (was bedeutet, dass Teile fehlen oder veraltet sein könnten).
Wenn du Fragen hast, hinterlasse ein Kommentar auf dem Issue oder melde dich über Discord. Wir helfen gerne und beantworten deine Fragen.
Wir wenden einen triangulären Git-Workflow an. Das bedeutet, dass alle Code-Änderungen zuerst auf dem Fork des Entwicklers veröffentlicht werden, und erst dann werden die Änderungen via Pull Request in das offizielle ecamp3-Repository eingefügt. Wenn du ein fortgeschrittener Git-Benutzer bist, kannst du dies auch selbst einrichten. In der Praxis sieht die Einrichtung dieses Arbeitsablaufs wie folgt aus:
-
Erstelle einen persönlichen Fork des zentralen Repositories auf GitHub. Um die Befehle zu verwenden, sollte der konfigurierte Git-Benutzername genau deinem GitHub-Benutzernamen entsprechen. Wenn du den folgenden Code ausführst und er dein GitHub-Benutzernamen ausgibt, bist du startklar.
echo $(git config user.name)
Wenn nicht, solltest du den
$(git config user.name)durch deinen Benutzernamen ersetzen oder den Befehlgit config --global user.name "DeinNutzername"mit deinem GitHub-Benutzernamen anstelle vonDeinNutzernameausführen. -
Klone das originale Repository auf deinen lokalen Computer:
git clone https://github.com/ecamp/ecamp3.git cd ecamp3 -
Füge deinen Fork als Remote hinzu:
git remote add "$(git config user.name)" "https://github.com/$(git config user.name)/ecamp3.git"
-
Konfiguriere Git, sodass es als aktuellen, offiziellen Code-Stand das zentrale Repository und fürs Veröffentlichen neuer Änderungen den Fork verwendet:
git config remote.pushdefault "$(git config user.name)" git config push.default current
Wenn dies eingerichtet ist kannst du loslegen, und alle git pull-Befehle sollten standardmässig den Code vom zentralen Repository holen und git push-Befehle sollten auf deinen eigenen Fork des Projekts senden.
Bevor du etwas am Code änderst, solltest du jeweils die folgenden Schritte durchführen, um mit einem sauberen Stand zu starten der später einfach gemerged werden kann:
git fetch --all
git checkout origin/devel
git checkout -b my-new-feature-branchWir verwenden cs-fixer für PHP und ESLint und Prettier für Javascript, HTML & CSS, um einen einheitlichen Codestil zu gewährleisten. Stelle sicher, dass dein Code automatisch formatiert wird, bevor du ihn committest und in das Repository stellst. Wir empfehlen dir, deine Entwicklungsumgebung so zu Konfigurieren, dass der Code beim Speichern automatisch formatiert wird.
Alternativ kannst du
-
php-cs-fixer und ESLint / Prettier manuell vor jedem Commit ausführen: (Klick mich an, ich bin aufklappbar)
# Frontend Dateien in einem bereits laufenden Container formatieren docker compose exec frontend npm run lint # API/PHP Dateien in einem bereits laufenden Container formatieren docker compose exec php composer cs-fix # Print Dateien in einem bereits laufenden Container formatieren docker compose exec print npm run lint # PDF Dateien in einem bereits laufenden Container formatieren docker compose exec pdf npm run lint # E2E Dateien in einem bereits laufenden Container formatieren docker compose run --rm --entrypoint="npm run lint" e2e
Wenn du keinen Container dieses Typs am laufen hast, verwende
runanstelle vonexecute. Beachte, dass dies einen neuen Docker-Container startet (was auf einem Gerät mit begrenzten Rechenressourcen eventuell nicht erwünscht ist).docker compose run --rm frontend npm run lint docker compose run --rm php composer cs-fix docker compose run --rm print npm run lint docker compose run --rm pdf npm run lint
-
einen pre-commit Git-Hook aufsetzen, um php-cs-fixer und ESLint automatisch vor jedem Commit ausführen zu lassen. Ein Beispiel dafür ist in der pre-commit.sh datei zu finden.
Um dieses Beispiel zu verwenden führe die folgenden Befehle aus (Klick mich an, ich bin aufklappbar)
Beachte, du gibst nun einer Datei aus dem Internet die Berechtigung auf deinem Computer ausgeführt zu werden. Es ist empfehlenswert in solchen Fällen sicherzustellen das du dem Code und Author vertraust. (Oder noch besser: verstehst, was der Code macht)# Einen Verweis auf die Datei erstellen, alternativ kannst du 'cp' anstelle von 'ln' verwenden um die Datei zu kopieren
ln ./pre-commit.sh .git/hooks/pre-commit
# Datei ausführbar machen
chmod +x .git/hooks/pre-commit
# Sieh dir an wie lange die Ausführung dauert und stelle sicher, dass alles funktioniert
time .git/hooks/pre-commitWir schätzen jeden Beitrag zu unserem Projekt sehr und sind dankbar dafür! ❤️ Um die Zusammenarbeit für alle reibungsloser und angenehmer zu gestalten, haben wir diese Prüfliste zusammengestellt 📜. Durch das Prüfen dieser Punkte verbesserst du die Qualität und Konsistenz deiner Beiträge ✨ und beschleunigst den Überprüfungsprozess 🚀.
- Synchronisation mit dem zentralen Repository: 🔄 Stelle sicher, dass dein Fork auf dem neuesten Stand des zentralen Repositories ist, um eine reibungslose Integration deiner Änderungen zu ermöglichen. GitHub-Dokumentation
- Lint: 🔧 Stelle sicher, dass Linters auf alle neuen oder geänderten Dateien angewendet wurden.
- Bedeutsame Änderungen: 🔎 Bestätige, dass jede geänderte Datei einen sinnvollen Inhalt beiträgt und vermeide unbedeutende Änderungen wie reine Anpassungen von Leerzeichen.
- Testing: 🧪 Schreibe Tests für alle neuen Funktionen und aktualisiere bestehende Tests, wenn du Änderungen an Funktionalitäten vorgenommen hast.
- Sprache & Rechtschreibung: 📖 Verwende Englisch für alle Variablennamen, Klassennamen, Funktionen, Kommentare usw., und stelle sicher, dass aller hinzugefügter Inhalt Rechtschreibprüfungen durchlaufen hat.
- Sensible Informationen: ⛔ Überprüfe vor dem Einreichen noch einmal, um sicherzustellen, dass keine Passwörter, Zugangsdaten oder lokale Konfigurationen in deinen Änderungen vorhanden sind.
- Kontinuierliche Integration: 🟢 Stelle sicher, dass der GitHub Actions CI-Build erfolgreich abgeschlossen werden kann, ohne Testfehler.
Um die Entwicklung zu vereinfachen und Konsistenz in lokalen Umgebungen zu gewährleisten, bieten wir einen vordefinierten Datensatz an, der als 'Dev-Daten' bekannt ist. Dieser Datensatz ist darauf ausgerichtet, dass wir beim Entwickeln immer eine breite Palette an realistischen Daten sowie einige bekannte Randfälle zur Verfügung haben.
Um dich in Entwicklungsumgebungen wie localhost:3000 einzuloggen, verwende die Benutzerdaten test@example.com / test.
Dieser Benutzer wurde mit einer umfassenden Sammlung von Lagern ausgestattet, die für das Testen der meisten Funktionen und Szenarien ausreichen sollten.
Wir bemühen uns ständig, unsere 'Dev-Daten' zu verbessern. Wenn du Lücken erkennst oder glaubst, dass es ein zusätzliches Szenario abdecken sollte, öffne bitte ein Issue, um uns darüber zu informieren.
Für ein tieferes Verständnis der 'Dev-Daten' haben wir dieses README (nur auf Englisch verfügbar) erstellt.
Die 'Dev-Daten' werden in allen Entwicklungsumgebungen repliziert. Wir empfehlen deren Verwendung für konsistente Tests. Wenn du ein Problem oder einen Fehler meldest: Referenziere doch ein spezifisches Beispiel aus den 'Dev-Daten'. Da die Daten, einschliesslich der IDs, konstant bleiben, kann jeder das von dir hervorgehobene Verhalten leicht nachvollziehen und reproduzieren.
Wir verstehen, dass das Einrichten einer Entwicklungsumgebung manchmal knifflig sein kann, besonders bei unterschiedlichen Systemen und Konfigurationen. Wenn du auf Probleme stösst oder Hindernissen während der Einrichtung begegnest, zögere bitte nicht, unserem Discord-Server beizutreten. Unser Kernteam und die Community helfen dir dort gerne weiter. Tatsächlich ermutigen wir dich, Fragen zu stellen, zu kollaborieren und Unterstützung auf Discord zu suchen, wann immer du bei einem Problem auf einen Stolperstein triffst. Dein Feedback hilft nicht nur dabei, den Einrichtungsprozess für alle zu verfeinern, sondern stellt auch sicher, dass potenzielle Probleme umgehend angegangen werden. Denk daran, unsere Unterstützung beschränkt sich nicht nur auf Einrichtungsfragen; du bist herzlich eingeladen, in unserer Discord-Community über alle anderen Themen zu diskutieren, auf die du in deiner Umsetzung stösst.
