From 7b5c474ac6d8c529b7cf625c736659ff1319c8b3 Mon Sep 17 00:00:00 2001 From: Ulli Hafner Date: Fri, 3 Apr 2020 15:22:28 +0200 Subject: [PATCH 1/3] Add documentation on how to work with GitHub. --- doc/Arbeiten-mit-GitHub.md | 259 +++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 doc/Arbeiten-mit-GitHub.md diff --git a/doc/Arbeiten-mit-GitHub.md b/doc/Arbeiten-mit-GitHub.md new file mode 100644 index 00000000..9eab2718 --- /dev/null +++ b/doc/Arbeiten-mit-GitHub.md @@ -0,0 +1,259 @@ +Disclaimer: Die folgende Anleitung ist unter großer Hilfe der folgenden beiden Tutorials entstanden: +- [How To Create a Pull Request on GitHub](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github) +- [GitHub Standard Fork & Pull Request Workflow](https://gist.githubusercontent.com/Chaser324/ce0505fbed06b947d962/raw/23b18d33a8e1a512c53155aabdf97042d8c63768/GitHub-Forking.md) + +# Arbeiten mit Pull Requests in GitHub + +Abgaben in GitHub werden über Pull Requests gestellt. Dazu sind die in den nachfolgenden Abschnitten beschriebenen +Schritte erforderlich. + +## Einen Fork erstellen + +Wer einen Pull Request mit seinen Ergebnissen stellen will, braucht zunächst einen +[Fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) des entsprechenden Projektes. Dies +geht nicht mit der Kommandozeile, sondern nur in der GitHub Oberfläche, siehe +[Anleitung](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository). +Dieser neu erstellte Fork ist zunächst eine exakte Kopie des Ausgangsprojektes, d.h. er enthält alle Commits, +Branches und Tags. + +## Mit dem Fork arbeiten + +Sobald der Fork erstellt wurde, ist dieser unter dem eigenen GitHub Benutzerkonto als Kopie sichtbar. Diese Kopie kann +dann mit folgendem Kommando auf den eigenen Rechner geholt werden: + +```shell +# Clone your fork to your local machine using SSH +git clone git@github.com:USERNAME/FORKED-PROJECT.git +``` +Falls noch kein SSH Schlüssel auf GitHub hinterlegt ist, lässt sich das alternativ auch mit HTTPS erledigen: + +```shell +# Clone your fork to your local machine using HTTPS +git clone https://github.com/USERNAME/FORKED-PROJECT.git +``` + +Für die einfache passwort-freie Nutzung von GitHub empfehle ich die +[Einrichtung von SSH](https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) +möglichst schnell nachzuholen. + +## Eigene Änderungen entwickeln + +Für jede Abgabe (und für jede noch so kleine Änderung am Projekt), **muss** ein neuer Branch angelegt werden. +Die Arbeit auf dem `master` Branch ist nicht sinnvoll, siehe auch das [Kapitel "Fork aktuell halten"](#den-fork-aktuell-halten). + +Um einen Branch anzulegen, sind folgende Schritte nötig: + +```shell +# Checkout the master branch - you want your new branch to come from master +git checkout master + +# Create a new branch named newfeature (give your branch its own simple informative name) +git branch newfeature + +# Switch to your new branch +git checkout newfeature +``` + +Nun geht es ans Programmieren und alle Änderungen werden Schritt für Schritt erstellt. +Hier hat sich das Test Driven Development bewährt, doch das soll nicht Teil dieser Anleitung sein. + +Ein weitere sinnvolle Vorgehensweise ist das schrittweise Entwickeln: Die Entwicklung wird nicht in einem +Rutsch durchgeführt und dann mit einem Commit abgeschlossen, sondern in mehreren Iterationen. Jeder Schritt, +der fehlerfrei übersetzt werden kann und bei dem danach alle Tests durchlaufen, sollte einzeln mit einem +Commit abgeschlossen werden. Dann lassen sich die Änderungen hinterher besser nachvollziehen. + +Beim Commit ist noch wichtig, eine gute Commit-Message zu vergeben, Chris Beam hat hierzu den hilfreichen Artikel +[How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) +geschrieben, der dies gut erklärt. + +## Pull Request vorbereiten + +Sobald alle Änderungen lokal mit einem Commit abgeschlossen wurden, können diese in den Fork auf GitHub integriert +werden. Dazu ist lediglich ein Push erforderlich: + +```shell +# Push the local branch newfeature to a remote branch in the forked repository (using the same name) +git push --set-upstream origin newfeature +``` + +Nun sind diese Änderungen auch Online im eigenen GitHub Projekt sichtbar. GitHub erkennt dort automatisch, +dass ein neuer Branch angelegt wurde und bietet eine entsprechende Schaltfläche in der Oberfläche an. +Alternativ kann auch über den +[Pull Request Dialog](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) +ein neuer Pull Request angelegt werden. + +Beim Anlegen des Pull Request muss nun ein Titel und eine Beschreibung eingegeben werden. Der Titel sollte den Namen +der Aufgabe enthalten, die Beschreibung ggf. weitere Details dazu. Verwenden von Anrede, Grußformel oder Schlussformel +sind nicht sinnvoll. + +*Vor* dem finalen Anlegen des Pull Request muss geprüft werden, ob der Pull Request die gewünschten Änderungen +enthält -- und auch nur diese! Dazu den Abschnitt Files im Dialog öffnen und die einzelnen Änderungen durchgehen. Tauchen dort +Änderungen auf, die nichts mit der Abgabe zu tun haben, so sind diese zu entfernen. Typischerweise sind dies Umformatierungen oder Leerzeilenänderungen +an nicht beteiligten Abschnitten oder gar komplett andere Dateien. + +## Den Fork aktuell halten + +Wichtig ist, diesen Fork immer aktuell zu halten, d.h. die Änderungen des Ausgangsprojektes +immer nachzuziehen. In den meisten Fällen genügt es, den sogenannten `master` Branch synchron zu halten. +Um dies zu ermöglichen, muss das Original Projekt als ein weiteres Remote hinzugefügt werden. Dazu hat sich der Name +`upstream` eingebürgert. Dies lässt sich mit folgendem Kommando umsetzen: + +```shell +# Add 'upstream' repo to list of remotes +git remote add upstream https://github.com/UPSTREAM-USER/ORIGINAL-PROJECT.git +``` + +Durch das folgende Kommando lässt sich die Konfiguration überprüfen: + +```shell +# Verify the new remote named 'upstream' +git remote -v +``` + +Dann sollte folgende Ausgabe erfolgen: + +```shell +origin git@github.com:USERNAME/FORKED-PROJECT.git (fetch) +origin git@github.com:USERNAME/FORKED-PROJECT.git (push) +upstream https://github.com/UPSTREAM-USER/ORIGINAL-PROJECT.git (fetch) +upstream https://github.com/UPSTREAM-USER/ORIGINAL-PROJECT.git (push) +``` + +Immer dann, wenn die Änderungen des `master` Branches vom Originalprojekt integriert werden sollen, können diese +mit folgendem Kommando eingebunden werden: + +```shell +# Fetch from upstream remote +git fetch upstream + +# View all branches, including those from upstream +git branch -va + +# Checkout your master branch and merge upstream +git checkout master +git merge upstream/master +``` + +Normalerweise sollte auf dem lokalen `master` Branch keine anderen Commits sein, daher wird ein +[fast-forward](https://git-scm.com/book/de/v2/Git-Branching-Einfaches-Branching-und-Merging) angewendet. + + +## Doing Your Work + +### Create a Branch +Whenever you begin work on a new feature or bugfix, it's important that you create a new branch. Not only is it proper git workflow, but it also keeps your changes organized and separated from the master branch so that you can easily submit and manage multiple pull requests for every task you complete. + +To create a new branch and start working on it: + +```shell +# Checkout the master branch - you want your new branch to come from master +git checkout master + +# Create a new branch named newfeature (give your branch its own simple informative name) +git branch newfeature + +# Switch to your new branch +git checkout newfeature +``` + +Now, go to town hacking away and making whatever changes you want to. + +## Submitting a Pull Request + +### Cleaning Up Your Work + +Prior to submitting your pull request, you might want to do a few things to clean up your branch and make it as simple as possible for the original repo's maintainer to test, accept, and merge your work. + +If any commits have been made to the upstream master branch, you should rebase your development branch so that merging it will be a simple fast-forward that won't require any conflict resolution work. + +```shell +# Fetch upstream master and merge with your repo's master branch +git fetch upstream +git checkout master +git merge upstream/master + +# If there were any new commits, rebase your development branch +git checkout newfeature +git rebase master +``` + +Now, it may be desirable to squash some of your smaller commits down into a small number of larger more cohesive commits. You can do this with an interactive rebase: + +```shell +# Rebase all commits on your development branch +git checkout +git rebase -i master +``` + +This will open up a text editor where you can specify which commits to squash. + +### Submitting + +Once you've committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. If you need to make any adjustments to your pull request, just push the updates to GitHub. Your pull request will automatically track the changes on your development branch and update. + +## Accepting and Merging a Pull Request + +Take note that unlike the previous sections which were written from the perspective of someone that created a fork and generated a pull request, this section is written from the perspective of the original repository owner who is handling an incoming pull request. Thus, where the "forker" was referring to the original repository as `upstream`, we're now looking at it as the owner of that original repository and the standard `origin` remote. + +### Checking Out and Testing Pull Requests +Open up the `.git/config` file and add a new line under `[remote "origin"]`: + +``` +fetch = +refs/pull/*/head:refs/pull/origin/* +``` + +Now you can fetch and checkout any pull request so that you can test them: + +```shell +# Fetch all pull request branches +git fetch origin + +# Checkout out a given pull request branch based on its number +git checkout -b 999 pull/origin/999 +``` + +Keep in mind that these branches will be read only and you won't be able to push any changes. + +### Automatically Merging a Pull Request +In cases where the merge would be a simple fast-forward, you can automatically do the merge by just clicking the button on the pull request page on GitHub. + +### Manually Merging a Pull Request +To do the merge manually, you'll need to checkout the target branch in the source repo, pull directly from the fork, and then merge and push. + +```shell +# Checkout the branch you're merging to in the target repo +git checkout master + +# Pull the development branch from the fork repo where the pull request development was done. +git pull https://github.com/forkuser/forkedrepo.git newfeature + +# Merge the development branch +git merge newfeature + +# Push master with the new feature merged into it +git push origin master +``` + +Now that you're done with the development branch, you're free to delete it. + +```shell +git branch -d newfeature +``` + + + +**Copyright** + +Copyright 2017, Chase Pettit + +MIT License, http://www.opensource.org/licenses/mit-license.php + +**Additional Reading** +* [Atlassian - Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) + +**Sources** +* [GitHub - Fork a Repo](https://help.github.com/articles/fork-a-repo) +* [GitHub - Syncing a Fork](https://help.github.com/articles/syncing-a-fork) +* [GitHub - Checking Out a Pull Request](https://help.github.com/articles/checking-out-pull-requests-locally) + + From 67978efe7251f5717e86b64dcabbfe542fe1e712 Mon Sep 17 00:00:00 2001 From: Ulli Hafner Date: Fri, 3 Apr 2020 15:49:36 +0200 Subject: [PATCH 2/3] Add actions description. --- doc/Arbeiten-mit-GitHub.md | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/doc/Arbeiten-mit-GitHub.md b/doc/Arbeiten-mit-GitHub.md index 9eab2718..193933a7 100644 --- a/doc/Arbeiten-mit-GitHub.md +++ b/doc/Arbeiten-mit-GitHub.md @@ -1,6 +1,6 @@ Disclaimer: Die folgende Anleitung ist unter großer Hilfe der folgenden beiden Tutorials entstanden: - [How To Create a Pull Request on GitHub](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github) -- [GitHub Standard Fork & Pull Request Workflow](https://gist.githubusercontent.com/Chaser324/ce0505fbed06b947d962/raw/23b18d33a8e1a512c53155aabdf97042d8c63768/GitHub-Forking.md) +- [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962) # Arbeiten mit Pull Requests in GitHub @@ -55,7 +55,8 @@ git checkout newfeature ``` Nun geht es ans Programmieren und alle Änderungen werden Schritt für Schritt erstellt. -Hier hat sich das Test Driven Development bewährt, doch das soll nicht Teil dieser Anleitung sein. +Hier hat sich das Test Driven Development bewährt, doch das soll nicht Teil dieser Anleitung sein +(siehe [Kapitel Testen](Testen.md) in meinen Kodierungsrichtlinien). Ein weitere sinnvolle Vorgehensweise ist das schrittweise Entwickeln: Die Entwicklung wird nicht in einem Rutsch durchgeführt und dann mit einem Commit abgeschlossen, sondern in mehreren Iterationen. Jeder Schritt, @@ -66,7 +67,7 @@ Beim Commit ist noch wichtig, eine gute Commit-Message zu vergeben, Chris Beam h [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) geschrieben, der dies gut erklärt. -## Pull Request vorbereiten +## Pull Request vorbereiten und stellen Sobald alle Änderungen lokal mit einem Commit abgeschlossen wurden, können diese in den Fork auf GitHub integriert werden. Dazu ist lediglich ein Push erforderlich: @@ -86,11 +87,37 @@ Beim Anlegen des Pull Request muss nun ein Titel und eine Beschreibung eingegebe der Aufgabe enthalten, die Beschreibung ggf. weitere Details dazu. Verwenden von Anrede, Grußformel oder Schlussformel sind nicht sinnvoll. -*Vor* dem finalen Anlegen des Pull Request muss geprüft werden, ob der Pull Request die gewünschten Änderungen -enthält -- und auch nur diese! Dazu den Abschnitt Files im Dialog öffnen und die einzelnen Änderungen durchgehen. Tauchen dort +**Vor** dem finalen Anlegen des Pull Request muss geprüft werden, ob der Pull Request die gewünschten Änderungen +enthält - und auch nur diese! Dazu den Abschnitt Files im Dialog öffnen und die einzelnen Änderungen durchgehen. Tauchen dort Änderungen auf, die nichts mit der Abgabe zu tun haben, so sind diese zu entfernen. Typischerweise sind dies Umformatierungen oder Leerzeilenänderungen an nicht beteiligten Abschnitten oder gar komplett andere Dateien. +Um solche Änderungen in den Pull Request zu integrieren, müssen diese mit dem bereits beschriebenen Workflow umgesetzt +werden: im Editor die Änderungen an den entsprechenden Dateien vornehmen, Commit lokal ausführen und dann wieder +mit Push auf das GitHub Projekt bringen. + +Schaut der Pull Request dann wie gewünscht aus, so kann er mit `Create` erzeugt werden. + +## Den Pull Request aktualisieren + +Sobald der Pull Request erzeugt wurde, wird dieser mit verschiedenen Tools automatisch überprüft. Welche Tools zum Tragen +kommen, hängt individuell vom Projekt ab. Typischerweise wird eine [Continuous Integration](Continuous-Integration.md) +gestartet, die einen Entwicklungs-Lebenszyklus ausführt: + +1. Compile +2. Test +3. Analyze + +Jeder dieser Schritte wird in GitHub mit einem *Ok* oder *Failed* Status markiert. Ist einer der Schritte mit *Failed* +markiert, muss der Pull Request überarbeitet werden. Dazu muss der Fehler analysiert werden und dann der Quelltext +an den passenden Stellen aktualisiert werden, sei es bei Compile- oder Testfehlern, bei Unterschreitung der geforderten +Testabdeckung oder bei Verstößen gegen die Kodierungsrichtlinien. + +Sind alle automatischen Tests auf *Ok* fehlt nur noch das Review des Autors des Orignal Projektes. Dies erfolgt +zeilenweise ebenfalls im Pull Request und kann mit den gleichen Schritten wie oben beschrieben eingearbeitet werden. +Normalerweise erkennt GitHub diese Änderungen automatisch, diese müssen daher nicht explizit als *Gelöst* markiert +werden. + ## Den Fork aktuell halten Wichtig ist, diesen Fork immer aktuell zu halten, d.h. die Änderungen des Ausgangsprojektes From 15f09a0096779096fac50abdfc73449a23253f00 Mon Sep 17 00:00:00 2001 From: Ulli Hafner Date: Fri, 3 Apr 2020 15:52:26 +0200 Subject: [PATCH 3/3] Remove original article. --- doc/Arbeiten-mit-GitHub.md | 125 +------------------------------------ 1 file changed, 2 insertions(+), 123 deletions(-) diff --git a/doc/Arbeiten-mit-GitHub.md b/doc/Arbeiten-mit-GitHub.md index 193933a7..68f15add 100644 --- a/doc/Arbeiten-mit-GitHub.md +++ b/doc/Arbeiten-mit-GitHub.md @@ -96,7 +96,7 @@ Um solche Änderungen in den Pull Request zu integrieren, müssen diese mit dem werden: im Editor die Änderungen an den entsprechenden Dateien vornehmen, Commit lokal ausführen und dann wieder mit Push auf das GitHub Projekt bringen. -Schaut der Pull Request dann wie gewünscht aus, so kann er mit `Create` erzeugt werden. +Schaut der Pull Request dann wie gewünscht aus, so kann er mit *Create* erzeugt werden. ## Den Pull Request aktualisieren @@ -113,7 +113,7 @@ markiert, muss der Pull Request überarbeitet werden. Dazu muss der Fehler analy an den passenden Stellen aktualisiert werden, sei es bei Compile- oder Testfehlern, bei Unterschreitung der geforderten Testabdeckung oder bei Verstößen gegen die Kodierungsrichtlinien. -Sind alle automatischen Tests auf *Ok* fehlt nur noch das Review des Autors des Orignal Projektes. Dies erfolgt +Sind alle automatischen Tests auf *Ok*, fehlt nur noch das Review des Autors des Orignal Projektes. Dies erfolgt zeilenweise ebenfalls im Pull Request und kann mit den gleichen Schritten wie oben beschrieben eingearbeitet werden. Normalerweise erkennt GitHub diese Änderungen automatisch, diese müssen daher nicht explizit als *Gelöst* markiert werden. @@ -163,124 +163,3 @@ git merge upstream/master Normalerweise sollte auf dem lokalen `master` Branch keine anderen Commits sein, daher wird ein [fast-forward](https://git-scm.com/book/de/v2/Git-Branching-Einfaches-Branching-und-Merging) angewendet. - - -## Doing Your Work - -### Create a Branch -Whenever you begin work on a new feature or bugfix, it's important that you create a new branch. Not only is it proper git workflow, but it also keeps your changes organized and separated from the master branch so that you can easily submit and manage multiple pull requests for every task you complete. - -To create a new branch and start working on it: - -```shell -# Checkout the master branch - you want your new branch to come from master -git checkout master - -# Create a new branch named newfeature (give your branch its own simple informative name) -git branch newfeature - -# Switch to your new branch -git checkout newfeature -``` - -Now, go to town hacking away and making whatever changes you want to. - -## Submitting a Pull Request - -### Cleaning Up Your Work - -Prior to submitting your pull request, you might want to do a few things to clean up your branch and make it as simple as possible for the original repo's maintainer to test, accept, and merge your work. - -If any commits have been made to the upstream master branch, you should rebase your development branch so that merging it will be a simple fast-forward that won't require any conflict resolution work. - -```shell -# Fetch upstream master and merge with your repo's master branch -git fetch upstream -git checkout master -git merge upstream/master - -# If there were any new commits, rebase your development branch -git checkout newfeature -git rebase master -``` - -Now, it may be desirable to squash some of your smaller commits down into a small number of larger more cohesive commits. You can do this with an interactive rebase: - -```shell -# Rebase all commits on your development branch -git checkout -git rebase -i master -``` - -This will open up a text editor where you can specify which commits to squash. - -### Submitting - -Once you've committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. If you need to make any adjustments to your pull request, just push the updates to GitHub. Your pull request will automatically track the changes on your development branch and update. - -## Accepting and Merging a Pull Request - -Take note that unlike the previous sections which were written from the perspective of someone that created a fork and generated a pull request, this section is written from the perspective of the original repository owner who is handling an incoming pull request. Thus, where the "forker" was referring to the original repository as `upstream`, we're now looking at it as the owner of that original repository and the standard `origin` remote. - -### Checking Out and Testing Pull Requests -Open up the `.git/config` file and add a new line under `[remote "origin"]`: - -``` -fetch = +refs/pull/*/head:refs/pull/origin/* -``` - -Now you can fetch and checkout any pull request so that you can test them: - -```shell -# Fetch all pull request branches -git fetch origin - -# Checkout out a given pull request branch based on its number -git checkout -b 999 pull/origin/999 -``` - -Keep in mind that these branches will be read only and you won't be able to push any changes. - -### Automatically Merging a Pull Request -In cases where the merge would be a simple fast-forward, you can automatically do the merge by just clicking the button on the pull request page on GitHub. - -### Manually Merging a Pull Request -To do the merge manually, you'll need to checkout the target branch in the source repo, pull directly from the fork, and then merge and push. - -```shell -# Checkout the branch you're merging to in the target repo -git checkout master - -# Pull the development branch from the fork repo where the pull request development was done. -git pull https://github.com/forkuser/forkedrepo.git newfeature - -# Merge the development branch -git merge newfeature - -# Push master with the new feature merged into it -git push origin master -``` - -Now that you're done with the development branch, you're free to delete it. - -```shell -git branch -d newfeature -``` - - - -**Copyright** - -Copyright 2017, Chase Pettit - -MIT License, http://www.opensource.org/licenses/mit-license.php - -**Additional Reading** -* [Atlassian - Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) - -**Sources** -* [GitHub - Fork a Repo](https://help.github.com/articles/fork-a-repo) -* [GitHub - Syncing a Fork](https://help.github.com/articles/syncing-a-fork) -* [GitHub - Checking Out a Pull Request](https://help.github.com/articles/checking-out-pull-requests-locally) - -