git.adoc

Aufbau und Umgang mit diesem Repository

Für die Erstellung von Artikeln und dazugehörigen Materialien gibt es verschiedene Verzeichnisse und einige Regeln. Die wichtigsten werden hier erklärt.

Verzeichnisse

Auf der obersten Ebene gibt es die folgenden Verzeichnisse:

de	Der Ort für alle Artikel in deutscher Sprache. Derzeit werden alle Artikel zuerst in Deutsch verfasst und danach auf Englisch übersetzt.
en	Der Ort für alle Artikel in englischer Sprache, sobald die deutsche Fassung fertig ist.
images	Die in den Artikeln verwendeten Bilder (Grafiken, Screenshots, Icons) werden hier abgelegt: Grafiken und Screenshots in einer flachen Hierarchie und die im Fließtext verwendeten Symbole (icons) in einer Höhe von 20 Pixeln im Unterverzeichnis icons.
attributes	Um das Schreiben zu erleichtern und um bestimmte Begrifflichkeiten und Formatierungen zu standardisieren, werden allgemeine Attribute hier definiert und angepasst.
contrib	Beinhaltet die Dokumentation zur Nutzung des Repositories.

Dateien

Zusätzlich gibt es ein paar mehr oder weniger hilfreiche Dateien, welche die Nutzung vereinfachen sollen:

checkmk.css

Diese Stylesheet-Datei ist eine adaptierte Version der für das Publishing verwendeten Datei. Sie kann benutzt werden, um beim Schreiben im Editor eine Live-Vorschau (preview) zu generieren, die der veröffentlichten Seite im Zielformat möglichst nahekommt.

Branches

Die Dokumentation von Checkmk erfolgt versionsbasiert, aber nicht editionsbasiert. Das bedeutet zum einen, dass die Unterschiede zwischen der Checkmk Raw Edition und den kommerziellen Editionen im gleichen Handbuch beschrieben werden.

Für jede stabile, veröffentlichte Version gibt es einen eigenen Branch. Dieser ist zu nutzen, wenn der Artikel oder die Korrektur für eine bereits erschienene Version von Checkmk gilt. Umgekehrt wird der Master immer für die Version von Checkmk genutzt, die sich gerade in Entwicklung befindet und noch nicht offiziell erschienen ist.

git Commit-Nachrichten

Unabhängig davon, ob es sich um reguläre Arbeiten der tribe29 oder um Pull Requests (PRs) handelt, sollte eine Commit-Nachricht immer hilfreich sein, um zu verstehen, was in dem Commit gemacht wurde. Dazu kann es manchmal auch notwendig sein, eine ausführlichere Beschreibung zu hinterlegen, um die Änderung inhaltlich zu begründen. Vor allem bei einem PR erleichtert es den Mitarbeitern von tribe29 die Arbeit erheblich, wenn Sie den Grund für eine Änderung schnell verstehen.

Einige Schlagwörter in den Commit-Nachrichten werden zur Verfolgung des Übersetzungsstatus verwendet. Wird eines der folgenden Schlagwörter am Beginn eines Commits benutzt, hat das die folgende Wirkung:

only-de	Dieser Commit betrifft nur Deutsch, muss nicht nach Englisch übersetzt werden und wird für den Übersetzungsstatus nicht berücksichtigt.
only-en	Das Pendant zu only-de.
content-sync	Der übergebene Artikel ist in beiden Sprachen inhaltlich vollständig synchron. Alle Commits, die vor diesem Datum in einer der beiden Sprachen erfolgt sind, werden automatisch quittiert und in Zukunft ignoriert. Dieses Schlagwort wird auch benutzt, um die Übergabe eines Artikels zur Übersetzung zu kennzeichnen, d.h.: Die Inhalte sind zwar synchron, aber nicht zwingend bereits übersetzt.

Beispiele zur Verwendung dieser git Commit-Nachrichten findest Du beim Thema Übersetzung.