CONTRIBUTING.md

Workflows
=========

Hinzufügen der Inhalte einer Vorlesung
--------------------------------------
- Für jede Vorlesung muss ein Issue mit dem Namen "Vorlesung vom dd.mm" erstellt
  werden.
- An dem Issue sollte vorrangig eine Person arbeiten und dies durch ein
  Assignment deutlich machen.
- Aus dem Issue sollte ein neuer Branch und ein Merge-Request (MR) mit der
  Option "Create merge request and branch" generiert werden.
- Der Titel des MR wird automatisch generiert und sollte mit "Draft" beginnen.
- Der MR muss mit dem Label `lecture` versehen werden.
- Der Austausch zu dem Issue sollte danach überwiegend im MR stattfinden.
- Sind alle Inhalte der Vorlesung codiert, muss das Label `tex-review`
  hinzugefügt werden und der MR als fertig markiert werden. Dies geschieht über
  die Option "Mark as ready".
- Eine andere Person trägt sich auf dem MR als Reviewer ein und prüft den
  LaTeX-Code. Insbesondere sind dabei die unten stehenden Richtlinien zu
  beachten.
- Nach einem erfolgreichen Review muss das Label `tex-review` vom Reviewer
  entfernt werden und das Label `pdf-review` hinzugefügt werden.
- Der Reviewer trägt sich als solcher aus dem MR aus.
- Eine weitere Person (potentiell der gleiche Reviewer) trägt sich auf dem MR
  als Reviewer ein und prüft das aus der Pipeline generierte PDF. Bei diesem
  Review geht es insbesondere um Formatierungen und sprachliche und
  mathematische Richtigkeit.
- Nach einem erfolgreichen Review muss das Label `pdf-review` vom Reviewer
  entfernt und der MR von Reviewer empfohlen werden. Dies geschieht über die
  Option "Approve" im MR.


GiT
===

Commits
-------
- Die erste Zeile einer Commit-Nachtricht sollte immer so geschrieben sein, dass
  sie den folgenden Satzanfang sinnvoll vervollständigt: "If applied, this
  commit will ... "
- Die erste Zeile einer Commit-Nachtricht sollte mit einem Großbuchstaben
  beginnen höchstens 72 Zeichen beinhalten und kein Satzzeichen am Ende
  beinhalten.


LaTeX Style
===========

Code
----
- Zeilen sollten oft und an sinnvollen Stellen umgebrochen werden. Speziell im
  Text (außerhalb von display-Umgebungen) sollte keine Zeile länger als 80
  Zeichen lang sein.
- Der Inhalt von Umgebungen (`\begin{...} ... \end{...}`) sollten immer 4
  Leerzeichen eingerückt werden.
- Manuelle Zeilenumbrüche durch `\newline`, `\linebreak` sollten vermieden
  werden.
- Der inline-Mathemodus sollte immer mit `\(` begonnen und mit `\)` beendet
  werden.
- Im inline-Mathemodus sollten keine Konstrukte verwendet werden, die den
  Zeilenabstand verändern, z.B. `\frac` oder `\sum`.
- Label sollten immer von der Struktur `<type>:<name>` sein. Dabei sollte `type`
  einen der Werte `lem`, `thm`, `ex`, `it`, `eq`, `chap`, `sec`, `def` oder
  `cor` annehmen. Bei dringendem Bedarf kann diese Liste durch einen weiteren
  maximal 4 Buchstaben langen Bezeichner ergänzt werden. Der `name` Teil sollte
  eine Kombination aus deutschsprachigen Wörtern und `-` sein und das zu
  referenzierende Objekt möglichst treffend beschreiben. Dabei sollten
  mathematische Bezeichner wie `f` oder `x` möglichst vermieden werden.
- Neue Befehle/Makros sollten mit einem englischen Bezeichner haben, der den
  mathematischen Inhalt transportiert, z.B. `\reals`, statt `\Rbb` für
  `\mathbb{R}`.

Inhalt
------
- Mathematische Formeln sollten immer in einen grammatikalisch korrekten Satz
  eingebunden werden.
- Abbildungen sollten immer in eine `figure` Umgebung gesetzt werden, mit einer
  `caption` versehen werden und mindestens einmal im Text referenziert werden.
- Konstrukte wie `\overset` und `\underbrace` sollten möglichst vermieden
  werden. Der Text und die Argumente sollten auch ohne die mit diesen
  Konstrukten hinzugefügten Informationen vollständig und verständlich sein.
- Sätze sollten nie mit einer mathematischen Formel beginnen. Beispiel: "f ist
  linear, da ..." -> "Die Funktion f ist linear, da ..."
- Mathematische Formeln die unterschiedlichen Satzelementen entsprechen sollten
  nicht direkt auf einander folgen.
- Die Anzahl an Relationszeichen/Umformungen die nicht von Text unterbrochen
  sind, sollten in der Regel auf 3 begrenzt sein.
- Die Umformungen in display-Umgebungen sollten in der Regel durch den
  voranstehenden Text erklärt werden. Beispiel: "Mit Lemma 4, der
  Dreiecksungleichnug und (3) folgt dann, dass"
- Symbole der formalen Logik (`\implies`,  `\Rightarrow`, `\forall`, `vee`, ...)
  sollten vermieden und durch Text ersetzt werden.

Übersetzen des Latex Codes
==========================

Zunächst muss das Repository mit

```sh
git clone https://scm.cms.hu-berlin.de/script-students/lina2/

```
geklont werden.

Sofern eine vollständige Version einer LaTeX-Distribution installiert ist, kann das PDF dann einfach mit

```sh
latexmk --norc -r .latexmkrc main.tex
```

generiert werden.

Alternativ definiert das Projekt auch eine Nix Entwicklungsumgebung, welche alle Abhängigkeiten bereitstellt.
Um deine Entwicklungsumgebung einzurichten, benötigst du Nix. Du kannst entweder zum [Nix-Installer-Repository](https://github.com/DeterminateSystems/nix-installer?tab=readme-ov-file#the-determinate-nix-installer) gehen oder den folgenden Befehl ausführen, um Nix mit nur einer Zeile zu installieren:

```sh
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix \
    | sh -s -- install
```

Wir empfehlen die Verwendung dieses Installationsprogramms, da es einige erforderliche Funktionen innerhalb von Nix konfiguriert, vorwiegend Flakes.

Anschließend kann das PDF mit

```sh
nix build
```

erzeugt werden.

> \[!NOTE\] Dieser Schritt kann beim ersten Ausführen einige Zeit in Anspruch nehmen, da Abhängigkeiten wie TexLive, Prettier und andere notwendige Tools installiert und kompiliert werden sowie Pre-Commit-Hooks eingerichtet werden.