# Contributing

Um einen reibungslosen Codeänderungsprozess zu gewährleisten, dient dieser Leitfaden sowohl als Regeln zum Umgang mit der GitHub-Repository als auch ein Guide zu Git und GitHub. Es wird hauptsächlich Android Studio's eingebauter Versionskontrollmanager verwendet, allerdings verläuft das Prinzip in allen anderen Git-Anwendungen ähnlich.

**Pusht auf gar keinen Fall Commits direkt in die `main` und `staging` Branches. Dadurch können Änderungen verloren gehen, und der Reviewprozess wird umgangen, wodurch fehlerhafter Code in unser Programm landet. Wenn ich jemanden beim Force-Push in die Mainbranches erwische, sorge ich dafür dass diese Person ihre Pushrechte verliert.**

## Struktur der Repository

Die Applikation wird in zwei Hauptbranches festgehalten:

- `main` -> Die Version der Applikation als Ergebnis einer Sprintiteration, mit End-Commits die jeweils getaggt sind
- `staging` -> Die Version der Applikation die die Ergebnisse vor der nächsten Sprints zusammenträgt, wird am Ende des Sprints in `main` geführt

Neben den Hauptbranches werden sogenannte "Feature Branches" geführt. Diese Branches enthalten jeweils *eine* Änderung (z.B. in einem Backlog Item ausgelegt), die in die `staging` Branch zusammengeführt wird, wenn die Änderung fertig ist.

## Codeänderungs-Prozess

Um eine Änderung an der Codebase vorzunehmen, muss diese Änderung in einem von `staging` abgespaltenen Branch aufgenommen werden. Diese sogenannte Featurebranches werden am Ende wieder in `staging` zusammengeführt. Der Prozess sollte Schritt für Schritt so verlaufen:

1. Zuerst wähle eine Änderung aus dem Backlog. Wenn diese in einer Projektitemzelle oder einem Issue steht, dann markiere Dich darin.
2. Erstelle einen Branch aus `staging` und benenne diese so: `<Euer Namenskürzel>/<Name des Features>` (ohne eckigen Klammern). So kann man in der Branchliste leicht erkennen woran eine Person arbeitet.
- Beachtet, dass Leerzeichen in einem Branchname nicht erlaubt ist.
- Wenn man eine Branch erstellt die nur `<Euer Namenskürzel>` (z.B. `studi`) heißt, dann kann man keine Branches wie oben benannt erstellen (z.B. `studi/my-change`).
3. Erstelle deine Commits auf diesem Branch. **Halte deinen Branch atomar, sprich nimm dir nur ein Feature pro Branch vor. Bei mehreren Features wird der Branch zu groß (richte dich nach maximal 2.000 Zeilenänderungen pro Branch).**
4. Pushe diesen Branch auf die Repository, und erstelle daraus eine "Pull Request" die auf `staging` zeigt. Schreibe eine kurze Beschreibung zu den Änderungen die man in dem Branch vorfinden kann. Wenn die Pull Request sich mit einem Issue befasst, kannst du in deine PR-Beschreibung `Closes #<Issuenummer>` oder `Fixes #<Issuenummer>` (z.B. `Fixes #123`) schreiben. Beim Mergen deiner PR wird diese Issue dann automatisch geschlossen.
6. **Merge deine Pull Request nicht selber.** Ping entweder mich oder jemand anderes der deine Pull Request reviewt.
7. Sobald jemand ein Review erstellt hat, kannst du dich damit auseinandersetzen (Änderung vornehmen, Fragen im Review beantworten usw.). Sind keine Probleme im Pull Request vorhanden, kann diese gemerged werden.

## Umgang mit Git in Android Studio/GitHub

### Projekt von GitHub clonen

1. Auf der Repositoryseite, klicke auf `Code` und kopiere den HTTPS-Link.


2. In Android Studio im Projektmanagerscreen, klicke auf `Get from VCS`, gib als URL den Link ein und klicke auf `Clone`.


3. Öffne das Projekt sobald es heruntergeladen ist.

Siehe: https://www.jetbrains.com/help/idea/set-up-a-git-repository.html#clone-repo

### Branch erstellen

1. Klicke im Hauptfenster auf den Knopf neben den Projektnamen, mit dem Namen des aktiven Branches.
2. Klicke auf dem Branchnamen den du als Basis nehmen möchtest, und klicke auf `Update`.
3. Klicke nochmal auf dem Branchnamen und wähle `Create branch from '<Branchname>'`
4. Wähle einen hilfreichen Namen, z.B. `studiname/my-feature`, und erstelle den Branch.

Siehe: https://www.jetbrains.com/help/idea/manage-branches.html#create-branch

### Branch wechseln

1. Klicke oben in der Leiste auf den Branchnamen.
2. Führe evtl. eine Fetch aus (gestrichelter Pfeil)
3. Klick auf einem Branch und wähle `Checkout`

Siehe: https://www.jetbrains.com/help/idea/manage-branches.html#checkout-Git-branch

### Commit erstellen

1. Wähle `Commit` aus der linken Seitenleiste (Kreis mit einer Linie hinter).


2. Das Seitenfenster zeigt eine Checkliste von Changes. Wähle die Dateien/Zeilen die man in dem Commit haben möchte.
3. Gib eine Commitnachricht an.
4. Klick auf `Commit`.

Siehe: https://www.jetbrains.com/help/idea/commit-and-push-changes.html#commit

### Änderungen von der GitHub Repository ziehen / Branchkonflikte lösen

1. Stell sicher dass du auf deinem Branch bist.
2. Wähle deine Targetbranch (z.B. `staging`) und klicke auf `Merge 'staging' into 'dein-branch'`.
3. Wähle `Merge` statt `Rebase`.
4. Wenn Konflikte auftreten, erscheint eine Liste von Dateien mit Konflikte. Löse jede Datei mit Konflikte individuell im Merge Editor (aufgerufen mit dem `Merge...`-Knopf oder Doppelklick).
5. Im Merge Editor gibt es drei Fenster: Das linke und rechte Fenster enthält die Versionen der Dateien jeweils der zwei Branches, und das mittlere Fenster ist das Ergebnis des Merges, sprich wie die Datei aussehen wird nachdem du mit dem Merge fertig bist.
6. Eine Datei ist erst fertig wenn keine Merge Changes mehr vorhanden ist. Du kannst die Anzahl der unerledigten Changes oben rechts im Merge Editor finden.
7. Klicke oben links neben `Apply non-conflicting changes` den `All` Knopf.
8. Mit den Pfeilen oben links kannst du zu Konflikten navigieren. Jeweils links und rechts gibt es an den Rändern der Fenster einen `Accept` und `Ignore` Knopf. Du kannst damit eine Kombination der Änderungen im Resultat übernehmen. Eventuell musst du den Code nach einem Konflikt ergänzen. **Achte beim Lösen eines Konflikts darauf, dass die Datei Sinn ergibt, also keine Syntax- oder Semantikfehler hat.**
9. Wenn die Datei keine Konflikte mehr erhält, klicke unten rechts auf `Apply`.
10. Sind keine Konflikte mehr vorhanden, wird der Merge von Android Studio automatisch fertiggestellt.

Siehe: https://www.jetbrains.com/help/idea/resolve-conflicts.html

### Branch + Änderungen auf die GitHub Repo pushen

1. Klicke wie oben auf den Branchnamen und wähle `Push`.
2. Wähle unten `Push` (kein `Force Push`).

Siehe: https://www.jetbrains.com/help/idea/commit-and-push-changes.html#push

### Pull Request erstellen

1. Öffne die GitHub Repo und navigiere zu `Pull requests`.
2. Klick `New pull request`.
3. Wähle als Basebranch z.B. `staging` und als Comparebranch deine Branch.
4. Klick `Create pull request`.
5. Gib einen Titel und Beschreibung an, evtl. mit [Closing Keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
6. Wenn du fertig bist, klick auf `Create pull request`.

Siehe: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request

### Änderungen in einem Pull Request anfragen

1. Wähle eine Pull Request aus.
2. Navigiere zu `Files changed`.
3. Wenn dir etwas auffällt, markiere die Zeilen Code in dem du auf der Zeilenleiste links mit der linken Maustaste gedrückt über die Zeilen ziehst. Klick dann auf das Pluszeichen.
4. Schreibe einen Kommentar.
5. Entweder kannst du eine Review starten, wodurch du mehrere Zeilen Code in einem Review kommentieren kannst, oder du kannst einen einfachen Kommentar abgeben.
6. Wenn du mit deinem Review fertig bist, scrolle wieder nach oben und klick rechts auf `Finish your review`.
7. Optional: Schreibe einen generellen Kommentar über deinen kompletten Review.
8. Wähle entweder `Comment` oder `Request changes` aus (`Approve` wird separat erklärt).
9. Schick deine Review ab.

Siehe: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request

### Pull Request approven

1. Wenn du in einem Pull Request keine Mängel vorfindest, klick in `Files changed` oben rechts auf `Review changes` und wähle `Approve` (optional: Kommentar).
2. Schick deine Review ab.

Siehe: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request

### Pull Request mergen

1. **Wenn es keine ausstehende Reviews gibt**, scrolle zu den Boden der PR-Seite. Branches mit Merge-Konflikte mit dem Targetbranch können nicht gemerged werden, siehe [hier wie man Konflikte löst](#Änderungen-von-der-GitHub-Repository-ziehen-/-Branchkonflikte-lösen).
2. Wähle `Merge pull request`. Stell sicher dass der Knopf nicht `Squash and merge` oder `Rebase and merge` heißt.
3. Klick `Confirm merge`.

Siehe: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request