Zum Inhalt

Git und Gitlab

Für Personen, die im Repository von dsstools committen wollen, wurden sich auf folgende Prinzipien und Grundlagen geeinigt.

Issues

Issues sollten vorzugsweise einen englischen Titel erhalten, der Inhalt kann auf deutsch sein. Das hat den Zweck, dass falls MRs über die GUI von Gitlab erzeugt werden, dann die entsprechenden MR-Titel und Branches ebenfalls englische Titel erhalten.

Issues sollten nach Möglichkeit eine sinnvolle und zielführende Beschreibung enthalten. Falls möglich, ist ein kurzes Beispiel oder eine Lösungsvorschlag anzugeben.

Wer sich ein Issue zuweist oder zugewiesen ist, kümmert sich selbstständig um dieses. Bei Rückfragen oder Hilfe pingt die entsprechenden Leute an.

Merge requests

Hier gelten ähnliche Regeln wie für Issues. Bitte auf einen sinnvollen Titel auf Englisch achten ("Resolve XYZ" ist nicht aussagekräftig). Auch hier sollte eine kurze Beschreibung des Lösungsansatzes aufgeführt sein, entweder auf Deutsch oder Englisch.

Falls andere Personen beteiligt sind, bitte mit der @-Notation verlinken. Für ein Review bitte die entsprechende Person auswählen. Das Review wird durchgeführt, sobald ihr den Draft-Status auf eurem Issue entfernt habt.

Verwendung von Branches

Branches werden meist in Zusammenhang zu Issues angelegt. Branches sollten einen sinnvollen Namen haben. Die automatische Erzeugung einer MR mit einem Branch von Gitlab funktioniert dafür eigentlich sehr gut.

Git commits

Committet bitte regelmäßig (pimaldaumen einmal in der Stunde) und pusht am Ende eurer Arbeit, auch wenn eure Änderungen möglicherweise zu fehlschlagenden Tests führen. Das macht es anderen Entwickler:innen einfacher, Änderungsvorschläge zwischendurch zu machen oder bei Hilfe schnell zu unterstützen.

Git commit messages

Git commit messages werden transparent und zugänglich gestaltet. Details dazu lassen sich hier nachlesen: https://cbea.ms/git-commit/ Konkret listet der Artikel folgende Richtlinien (auf Englisch):

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Konkret sieht eine ausführliche Commit message dann wie folgt aus:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Bitte haltet euch daran, ansonsten kann eure MR abgelehnt werden.

Git rebase

Gewisse Grundkenntnisse von Git werden vorausgesetzt. Dazu gehören insbesondere der Umgang mit Branches (s.o.), Commit/Staging und Rebasing.

Rebasing sollte immer gegenüber Merges für das Updaten von Branches vorgezogen werden. Zum Thema Rebasing findet ihr für die IDE (und allgemein) hier einen guten Überblick zu Konzepten und der Verwendung: https://www.jetbrains.com/help/pycharm/apply-changes-from-one-branch-to-another.html#rebase-branch

Rebasing ermöglicht auch mit dem interactive rebasing ein Umschreiben der eigenen Historie. Verwendet dies bitte nur in eurem lokalen Branch, da das schnell zu Problemen führen kann, wenn andere auf eurem Branch arbeiten: https://www.jetbrains.com/help/pycharm/apply-changes-from-one-branch-to-another.html#interactive-rebase

Personen, die kein PyCharm nutzen, lesen sich bitte selbst in Rebasing und interactive rebase ein.

Bei Fragen oder auftretenden Problemen steht David gerne zur Verfügung.