389 lines
16 KiB
Markdown
389 lines
16 KiB
Markdown
# Cheat-Sheet für Kubernetes-Beitragende
|
|
|
|
|
|
Eine Liste von oft-genutzten Ressourcen zum Beitragen zu Kubernetes; Tipps, Tricks
|
|
und allgemeine Best-Practices innerhalb des Kubernetes-Projekts.
|
|
Es ist als "TL;DR" (too long, didn't read - zu lang, nicht gelesen) oder Schnellreferenz
|
|
nützlicher Informationen gedacht, um deine Beitragserfahrung auf GitHub besser zu machen.
|
|
|
|
**Inhaltsverzeichnis**
|
|
- [Hilfreiche Ressourcen](#Hilfreiche-Ressourcen)
|
|
- [Wie man anfängt](#Wie-man-anfängt)
|
|
- [SIGs und andere Gruppen](#SIGS-und-andere-Gruppen)
|
|
- [Community](#Community)
|
|
- [Important Email Aliases](#Important-Email-Aliases)
|
|
- [Ablauf](#Ablauf)
|
|
- [Tests](#Tests)
|
|
- [Wichtige Email-Adressen](#Wichtige-Email-Adressen)
|
|
- [Andere nützliche Links](#Andere-Nützliche-Links)
|
|
- [Effektive Kommunikation auf GitHub](#Effektive-Kommunikation-auf-GitHub)
|
|
- [Seid exzellent zueinander](#Seid-exzellent-zueinander)
|
|
- [Beispiele für gute/schlechte Kommunikation](#Beispiele-für-guteschlechte-Kommunikation)
|
|
- [Einen Beitrag einreichen](#Einen-Beitrag-einreichen)
|
|
- [Das CLA unterzeichnen](#Das-CLA-unterzeichnen)
|
|
- [Erstellen von und Antworten auf Issues](#Erstellen-von-und-Antworten-auf-Issues)
|
|
- [Erstellen eines Issues](#Erstellen-eines-Issues)
|
|
- [Antworten auf Issues](#Antworten-auf-Issues)
|
|
- [Öffnen eines Pull-Requests](#Öffnen-eines-Pull-Requests)
|
|
- [Erstellen eines Pull-Requests](#Erstellen-eines-Pull-Requests)
|
|
- [Beispiel PR-Beschreibung](#Beispiel-PR-Beschreibung)
|
|
- [Troubleshooting eines Pull-Requests](#Troubleshooting-eines-Pull-Requests)
|
|
- [Labels](#Labels)
|
|
- [Lokal arbeiten](#Lokal-arbeiten)
|
|
- [Branch-Strategie](#Branch-Strategie)
|
|
- [Upstream-hinzufügen](#Upstream-hinzufügen)
|
|
- [Synchron halten von Forks](#Synchron-halten-von-Forks)
|
|
- [Commits squashen](#Commits-squashen)
|
|
|
|
---
|
|
|
|
## Hilfreiche Ressourcen
|
|
|
|
### Wie man anfängt
|
|
|
|
- [Contributor Guide] - Anleitung zum Beginn des Beitragens zum Kubernetes-Projekt.
|
|
- [Developer Guide] - Anleitung zum Beitragen von Code direkt zum Kubernetes-Projekt.
|
|
- [Security and Disclosure Information] - Anleitung zum Melden von Schwachstellen und
|
|
zur Sicherheit des Release-Prozesses.
|
|
|
|
### SIGs und andere Gruppen
|
|
|
|
- [Gruppenliste][SIGs]
|
|
|
|
### Community
|
|
|
|
- [Kalender] - Alle Kubernetes-Community-Events (SIG/WG Treffen, Events, usw.).
|
|
- [kubernetes-dev] - Kubernetesentwicklung-Mailingliste.
|
|
- [Kubernetes Forum] - Offizielles Kubernetes-Forum.
|
|
- [Slack Channels] - Offizieller Kubernetes-Slackchannel.
|
|
- [Stack-Overflow] - Zum Stellen von Kubernetes-Nutzerfragen.
|
|
- [YouTube Channel] - Offizieller Kubernetes-Youtubechannel.
|
|
|
|
|
|
### Ablauf
|
|
|
|
- [Prow] - Kubernetes CI/CD-System.
|
|
- [Tide] - Prow-Plugin das Merges und Tests verwaltet. [Tide Dashboard]
|
|
- [Bot-Befehle] - Befehle zur Interaktion mit Kubernetes-Bots (zum Beispiel: `/cc`, `/lgtm`, und `/retest`)
|
|
- [GitHub Labels] - Liste an Labels des ganzen Kubernetes-Projekts.
|
|
- [Kubernetes Code Search], von [@dims] maintained.
|
|
|
|
|
|
### Tests
|
|
|
|
- [Prow] - Kubernetes CI/CD-System.
|
|
- [Test Grid] - Ansicht historischer Tests und den zugehörigen Informationen.
|
|
- [Triage Dashboard] - Aggregiert ähnliche Fehler zur besseren Fehlerbehandlung.
|
|
|
|
|
|
### Wichtige Email-Adressen
|
|
|
|
- community@kubernetes.io - Maile jemandem im Community-Team (SIG Contributor
|
|
Experience) über ein Problem in der Community.
|
|
- conduct@kubernetes.io - Kontaktiere das Code-of-Conduct-Board, private Mailingliste.
|
|
- github@kubernetes.io - Maile dem [GitHub Administration Team] privat,
|
|
für heikle Themen.
|
|
- steering@kubernetes.io - Maile der Leitungsgruppe. Öffentliche Adresse mit
|
|
öffentlichem Archiv.
|
|
- steering-private@kubernetes.io - Maile der Leitungsgruppe private, für heikle Themen.
|
|
- social@cncf.io - Kontaktiere das CNCF Socal Media Team; Blog, Twitteraccount, und
|
|
andere soziale Bereiche.
|
|
|
|
|
|
### Andere nützliche Links
|
|
|
|
- [Developer Statistiken] - Entwicklerstatistiken für alle von CNCF gemanagten Projekte.
|
|
|
|
---
|
|
|
|
## Effektive Kommunikation auf GitHub
|
|
|
|
|
|
### Seid exzellent zueinander
|
|
|
|
Als ersten Schritt sollte man sich mit dem [Code of Conduct] bekannt machen.
|
|
|
|
|
|
#### Beispiele für gute/schlechte Kommunikation
|
|
|
|
Wenn man ein Problem anspricht, oder Hilfe sucht, sollte man die Anfrage höflich
|
|
formulieren:
|
|
|
|
🙂 “X kompiliert nicht, wenn ich Y mache, habt ihr Vorschläge dazu?
|
|
|
|
😞 “X geht nicht, fixt das!"
|
|
|
|
Beim Schließen eines PRs ist es sinnvoll eine freundliche und erklärende Nachricht
|
|
hinzuzufügen weshalb dieser nicht die Mergeanforderungen erfüllt.
|
|
|
|
🙂 “Ich schließe diesen PR, da dieses Feature nicht den Use-Case X unterstützt. In
|
|
der forgeschlagenen Form wäre es besser dies mit Y umzusetzen. Danke für deine
|
|
Mitarbeit daran."
|
|
|
|
😞 “Warum folgt das nicht den API-Konventionen? Das sollte woanders gemacht werden!"
|
|
|
|
---
|
|
|
|
## Einen Beitrag einreichen
|
|
|
|
### Das CLA unterzeichnen
|
|
|
|
Bevor man einen Beitrag einreichen kann, muss das [Contributor License Agreement (CLA) unterzeichnet][cla]
|
|
werden. Das Kubernetes-Projekt kann _nur_ einen Beitrag annehmen, wenn du oder deine Firma
|
|
das CLA unterzeichnet haben.
|
|
|
|
Solltest du Probleme beim Unterzeichnen des CLAs haben, folge den [CLA Troubleshooting Guidelines][CLA
|
|
troubleshooting guidelines].
|
|
|
|
|
|
### Erstellen von und Antworten auf Issues
|
|
|
|
GitHub Issues sind der meistgenutzte Weg um Dinge wie Bugreports und Enhancementrequests
|
|
zu verfolgen, oder andere Probleme wie fehlschlagende Tests zu melden.
|
|
Sie sind **nicht** als [Anfragen für Usersupport][user support requests] gedacht. Für diese
|
|
gibt es den [Troubleshooting Guide][troubleshooting guide], [Stack-Overflow] oder das
|
|
[Kubernetes-Forum][Kubernetes Forum].
|
|
|
|
**Referenzen:**
|
|
- [Labels]
|
|
- [Prow Commands][commands]
|
|
|
|
|
|
#### Erstellen eines Issues
|
|
|
|
- Nutze ein Issue-Template, wenn eines zur Verfügung steht. Das korrekte Template
|
|
hilft anderen Beitragenden auf deinen Issue zu antworten.
|
|
- Folge allen Anweisungen im Template selbst.
|
|
- Beschreibe den Issue detailliert.
|
|
- Füge sinnvolle [Labels][Labels] hinzu. Wenn du dir nicht sicher bist, hilft
|
|
der [K8s-ci-robot][Prow] Bot ([Kubernetes CI bot][Prow]) mit Antworten auf Issues,
|
|
damit diese effektive verwaltet werden.
|
|
- Sei selektiv beim Zuweisen von Issues zu Nutzern mit [`/assign @<username>`][assign]
|
|
oder [`/cc @<username>`][cc]. Der Issue wird effektiver verwaltet, wenn sinnvolle
|
|
Labels zugewiesen werden und weniger Menschen.
|
|
|
|
|
|
#### Antworten auf Issues
|
|
|
|
- Wenn du an einem Issue arbeitest, hinterlasse einen Kommentar damit andere
|
|
wissen, dass du daran arbeitest und doppelte Arbeit vermieden wird.
|
|
- Falls du selbst eine Lösung findest, kommentiere den Issue mit einer Erklärung
|
|
bevor du ihn schließt.
|
|
- Referenzen auf andere PRs und Issues (oder andere Materialen) mit zum Beispiel:
|
|
_"ref: #1234"_ sind sinnvoll. Diese helfen Bezüge darauf zu finden, die an
|
|
anderer Stelle bearbeitet wurden.
|
|
|
|
|
|
### Öffnen eines Pull-Requests
|
|
|
|
Pull-Requests (PR) sind die meistgenutzte Variante um Code, Dokumentation oder andere Arten
|
|
von Arbeit beizutragen, die in einem Git-Repository gespeichert werden können.
|
|
|
|
**Referenzen:**
|
|
- [Labels]
|
|
- [Prow Commands][commands]
|
|
- [Pull-Request Prozess]
|
|
- [GitHub Workflow]
|
|
|
|
|
|
#### Erstellen eines Pull-Requests
|
|
|
|
- Folge den Anweisungen des Pull-Request-Templates, falls eines zur Verfügung steht.
|
|
Es wird denen helfen, die auf den PR antworten.
|
|
- Für [triviale Fixes][trivial fix] wie kaputte Links, Schreib- oder Grammatikfehler
|
|
durchsuche das gesamte Dokument für andere potentielle Fehler. Mehrere PRs für kleine
|
|
Fixes im gleichen Dokument sind unnötig.
|
|
- Füge Referenzen auf verwandte Issues oder Issues die der PR lösen könnte hinzu.
|
|
- Vermeide unnötig große Änderungen in einem einzelnen Commit. Zerteile stattdessen
|
|
den PR in mehrere kleine, logische Commits. Das erleichter Reviews.
|
|
- Kommentiere deinen eigenen PR wenn du meinst weitere Erklärungen sind nötig.
|
|
- Sei selektiv beim Erstellen des PRs mit [`/assign @<username>`][assign].
|
|
Zu viele Reviewer garantieren keinen schnelleren PR-Review.
|
|
- Wenn der PR als _"Work in progress"_ angesehen wird, füge ein `[WIP]` am Anfang des
|
|
Titels hinzu oder nutze den [`/hold`][hold] Befehl. Das stellt sicher, dass der PR
|
|
nicht gemerged wird bis das `[WIP]` oder hold aufgehoben worden sind.
|
|
- Falls dein PR noch nicht reviewed wurde, bitte schließe ihn nicht und öffne einen Neuen
|
|
mit den gleichen Änderungen. Pinge deine Reviewer stattdessen in einem Kommentar mit
|
|
`@<github username>` an.
|
|
|
|
|
|
#### Beispiel PR-Beschreibung
|
|
|
|
```
|
|
Ref. #3064 #3097
|
|
Alle Dateien im Besitz von SIG testing wurden von `/devel` zum neuen Ordner `/devel/sig-testing`
|
|
verschoben.
|
|
|
|
/sig contributor-experience
|
|
/cc @stakeholder1 @stakeholder2
|
|
/kind cleanup
|
|
/area developer-guide
|
|
/assign @approver1 @approver2 @approver3
|
|
```
|
|
|
|
Was steht in diesem PR:
|
|
- **Zeile 1** - Referenzen auf andere Issues oder PRs (#3064 #3097).
|
|
- **Zeile 2** - Eine kurze Beschreibung was in diesem PR getan wird.
|
|
- **Zeile 4** - [SIG][SIGs] Zuweisung mit dem [Befehl][commands]
|
|
`/sig contributor-experience`..
|
|
- **Zeile 5** - Reviewer die Interesse an diesem spezifischen Issue oder PR
|
|
haben könnten, werden mit [`/cc`][cc] markiert.
|
|
- **Zeile 6** - Der [`/kind cleanup`][kind] Befehl fügt ein [Label][Labels] hinzu, das
|
|
Issues oder PRs als Aufräumen von Code, Prozessen oder technologischer Schuld kategorisiert.
|
|
- **Zeile 7** - Der [`/area developer-guide`][kind] Befehl kategorisiert Issues oder PRs im Bezug
|
|
zum Developerguide.
|
|
- **Zeile 9** - Der Befehl [`/assign`][assign] fügt einen Approver zum PR hinzu. Ein Approver
|
|
wird vom [k8s-ci-robot][Prow] vorgeschlagen und wird von der Liste der Eingentümer in der
|
|
[OWNERS] Datei ausgewählt. file. Der Approver fügt das [`/approve`][approve] Label zum PR
|
|
hinzu nachdem dieser reviewed wurde.
|
|
|
|
|
|
#### Troubleshooting eines Pull-Requests
|
|
|
|
Nachdem ein PR vorgeschlagen wurde, wird eine Reihe an Test von der Kubernetes
|
|
CL-Plattform [Prow] ausgeführt. Fall einer der Tests fehlschlägt, antwortet
|
|
der [K8s-ci-robot][Prow] auf den PR mit Links zu den fehlgeschlagenen Tests und
|
|
verfügbaren Logs.
|
|
|
|
Neue Commits zu diesem PR sorgen dafür dass diese Tests erneut ausgeführt werden.
|
|
|
|
Gelegentlich gibt es Probleme mit der Kubernetes CI-Plattform. Diese können aus
|
|
verschiedenen Gründen auftreten, selbst wenn der Beitrag alle lokalen Tests besteht.
|
|
Man kann einen neuen Testdurchlauf mit dem `/retest` Befehl auslösen.
|
|
|
|
Für mehr Informationen zum Troubleshooting von spezifischen Test, siehe den [Testing Guide].
|
|
|
|
|
|
### Labels
|
|
|
|
Kubernetes nutzt [Labels][Labels] zum sichten und kategorisieren von Issues und Pull Requests.
|
|
Die richtigen Labels helfen dabei den Issue oder PR sinnvoller einzusortieren.
|
|
|
|
**Referenzen:**
|
|
- [Labels]
|
|
- [Prow Commands][commands]
|
|
|
|
Oft genutzte Labels:
|
|
- [`/sig <sig name>`][kind] Fügt eine [SIG][SIGs] als Eigentümer des Issues oder PRs hinzu.
|
|
- [`/area <area name>`][kind] Verknüpft den Issue oder PR mit einem bestimmten [Bereich][labels].
|
|
- [`/kind <category>`][kind] [Kategorisiert][labels] den Issue oder PR.
|
|
|
|
---
|
|
|
|
## Lokal arbeiten
|
|
|
|
Bevor man einen Pull-Request vorschlagen kann, muss man lokal etwas Arbeit leisten.
|
|
Für Neueinsteiger zu git ist das [Atlassian Git-Tutorial][Atlassian git tutorial]
|
|
ein guter Einstiegspunkt. Alternativ ist das [Git Magic Tutorical][Git magic] der
|
|
Standford Uni eine gute multi-linguale Option.
|
|
|
|
**Referenzen:**
|
|
- [Atlassion Git-Tutorial][Atlassian git tutorial]
|
|
- [Git magic]
|
|
- [GitHub Workflow]
|
|
- [Lokakes Testen][Testing locally]
|
|
- [Developer guide]
|
|
|
|
|
|
### Branch-Strategie
|
|
|
|
Das Kubernetes-Projekt nutzt den Standardworkflow von GitHub, der sich _"Fork and Pull"_
|
|
(auf Deutsch "abzweigen und ziehen") nennt.
|
|
In Begriffen aus der Git-Welt wird dein persönlicher Fork als _"`origin`"_
|
|
(auf Deutsch "Ursprung") und das eigentliche Projekt-Gitrepository als _"`upstream`"_
|
|
(wörtlich "flussaufwärts") bezeichnet.
|
|
Um deinen persönlichen Branch (`origin`) mit dem Projekt (`upstream`) aktuell zu halten,
|
|
muss das innerhalb der lokalen Kopie konfiguriert werden.
|
|
|
|
|
|
#### Upstream hinzufügen
|
|
|
|
Füge `upstream` als sogenanntes remote hinzu und konfiguriere es so, dass man nicht dorthin
|
|
pushen kann.
|
|
|
|
```
|
|
# Ersetze <upstream git repo> mit der Upstreamrepo-URL
|
|
# Beispiel:
|
|
# https://github.com/kubernetes/kubernetes.git
|
|
# git@github.com/kubernetes/kubernetes.git
|
|
|
|
git remote add upstream <upstream git repo>
|
|
git remote set-url --push upstream no_push
|
|
```
|
|
|
|
Das kann via `git remote -v` verifiziert werden, indem alle konfigurierten Remote-Repos
|
|
aufgelistet werden.
|
|
|
|
|
|
#### Synchron halten von Forks
|
|
|
|
Hole alle Änderungen von `upstream` ab und _"rebase"_ diese auf deinem lokalen
|
|
`Master` Branch. Das wird dein lokales Repo mit dem `upstream` Projekt synchronisieren.
|
|
|
|
```
|
|
git fetch upstream
|
|
git checkout master
|
|
git rebase upstream/master
|
|
```
|
|
|
|
Das sollte minimal bevor der Erstellung eines neuen Branches für ein Feature oder
|
|
einen Fix passieren.
|
|
|
|
```
|
|
git checkout -b myfeature
|
|
```
|
|
|
|
#### Commits squashen
|
|
|
|
Der Hauptzweck von [Commits squashen]("Commits zerquetschen") ist die Erstellung
|
|
einer sauberen, lesbaren Githistorie oder eines Logs der Änderungen die gemacht wurden.
|
|
Normal wird das in der letzten Phase einer PR Revision getan. Wenn du dir unsicher bist,
|
|
ob du deine Commits squashen solltest, ist es besser mehrere zu lassen und es dem Urteil
|
|
anderer Beitragenden zu überlassen, die als Reviewer und Approver für den PR zugeteilt wurden.
|
|
|
|
|
|
[Contributor Guide]: /contributors/guide/README.md
|
|
[Developer Guide]: /contributors/devel/README.md
|
|
[Prow]: https://prow.k8s.io
|
|
[Tide]: https://sigs.k8s.io/prow/site/content/en/docs/components/core/tide/pr-authors.md
|
|
[Tide Dashboard]: https://prow.k8s.io/tide
|
|
[Bot-Befehle]: https://go.k8s.io/bot-commands
|
|
[GitHub Labels]: https://go.k8s.io/github-labels
|
|
[Kubernetes Code Search]: https://cs.k8s.io/
|
|
[@dims]: https://github.com/dims
|
|
[Kalender]: https://calendar.google.com/calendar/embed?src=calendar%40kubernetes.io
|
|
[kubernetes-dev]: https://groups.google.com/forum/#!forum/kubernetes-dev
|
|
[Slack Channels]: http://slack.k8s.io/
|
|
[Stack-Overflow]: https://stackoverflow.com/questions/tagged/kubernetes
|
|
[Youtube Channel]: https://www.youtube.com/c/KubernetesCommunity/
|
|
[Triage Dashboard]: https://go.k8s.io/triage
|
|
[Test Grid]: https://testgrid.k8s.io
|
|
[Developer Statistiken]: https://k8s.devstats.cncf.io
|
|
[Code of Conduct]: /code-of-conduct.md
|
|
[user support requests]: /contributors/guide/issue-triage.md#determine-if-its-a-support-request
|
|
[troubleshooting guide]: https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/
|
|
[Kubernetes Forum]: https://discuss.kubernetes.io/
|
|
[Pull-Request Prozess]: /contributors/guide/pull-requests.md
|
|
[GitHub Workflow]: /contributors/guide/github-workflow.md
|
|
[Prow]: https://sigs.k8s.io/prow/pkg
|
|
[cla]: /CLA.md#how-do-i-sign
|
|
[CLA troubleshooting guidelines]: /CLA.md#troubleshooting
|
|
[commands]: https://prow.k8s.io/command-help
|
|
[kind]: https://prow.k8s.io/command-help#kind
|
|
[cc]: https://prow.k8s.io/command-help#cc
|
|
[hold]: https://prow.k8s.io/command-help#hold
|
|
[assign]: https://prow.k8s.io/command-help#assign
|
|
[SIGs]: /sig-list.md
|
|
[Testing Guide]: /contributors/devel/sig-testing/testing.md
|
|
[Labels]: https://git.k8s.io/test-infra/label_sync/labels.md
|
|
[trivial fix]: /contributors/guide/pull-requests.md#10-trivial-edits
|
|
[GitHub Workflow]: /contributors/guide/github-workflow.md#3-branch
|
|
[Commits squashen]: /contributors/guide/pull-requests.md#6-squashing-and-commit-titles
|
|
[OWNERS]: /contributors/guide/owners.md
|
|
[Testing locally]: /contributors/guide/README.md#testing
|
|
[Atlassian git tutorial]: https://www.atlassian.com/git/tutorials
|
|
[Git magic]: http://www-cs-students.stanford.edu/~blynn/gitmagic/
|
|
[Security and Disclosure Information]: https://kubernetes.io/docs/reference/issues-security/security/
|
|
[approve]: https://prow.k8s.io/command-help#approve
|
|
[GitHub Administration Team]: /github-management#github-administration-team
|