Getting Started Guide for extension development

.gitignore

@@ -19,6 +19,8 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
+/tmp
+
 # Generated by the build process
 /sidebar.reference.json
 

CONTRIBUTING.md

@@ -1,5 +1,36 @@
 # mittwald Developer Portal -- Contribution guide
 
+## How We Write Docs
+
+Good documentation is clear, concrete, and welcoming—for every reader, not just experts.
+Our best guides feel like they’re written by your past self for someone brand new (and curious, but occasionally confused).
+
+**Our documentation principles:**
+
+- **Empathy:**
+  Write from the perspective of someone new to the project. If any step or term requires background knowledge, briefly introduce or link it.
+- **No “Magic Steps”:**
+  Don’t assume “everyone just knows”; if there are exceptions, limitations, or special cases, mention them or provide a link.
+- **Assumptions Are Bugs:**
+  If you write “simply”, “as usual”, or “just”, double check: is something being skipped?
+- **Consistency:**
+  Use the same terms throughout and stick to our tone (“du” in German, informal but clear in English).
+- **Concrete Examples:**
+  Prefer one fully worked, real-world example over several hand-wavey ones.
+- **Beginner’s Mind:**
+  Review your docs as if you have never seen the code or platform before. What would confuse you?
+- **Collaboration:**
+  If you trip over docs, make a note and suggest an improvement—or even just open an issue with your confusion.
+- **Document Gaps:**
+  If you uncover any “forbidden knowledge” or mistakes only an expert could know, *write it down for future contributors*.
+- **Respect the Reader’s Focus:**
+  Avoid leaving readers guessing by referencing “exceptions” or “special rules” without links, examples, or lists.
+
+**Remember:**
+Every bit of clear, concrete documentation you contribute saves time and frustration for the next team member—even if that person is you!
+
+If you’re unsure about something, ask for feedback: your “stupid question” might be the most valuable thing for future docs.
+
 ## Contributing docs
 
 The main documentation files are written in [Markdown][md] or [MDX][mdx] (also have a look at the [Docusaurus-specific Markdown features][docu-md]). You can find the documentation files in the following folders:

docs/contribution/20-glossary.mdx → docs/contribution/10-glossary.mdx

@@ -1,5 +1,6 @@
 ---
 title: Glossary
+sidebar_position: 2
 ---
 
 ## Contributor

docs/contribution/20-getting-started/02-become-contributor.mdx

@@ -0,0 +1,36 @@
+---
+title: Contributor werden
+---
+
+Contributor zu werden ist einfach.
+Du brauchst lediglich eine Organisation, die du über das mStudio anlegen kannst.
+Organisationen repräsentieren Unternehmungen, über die Leistungen – zum Beispiel zu Extensions – abgerechnet werden können.
+Bei unseren Hosting-Produkten sind dies beispielsweise Rechnungen.
+Im Falle von Contributoren werden die Gutschriften für die gebuchten Extensions über die Organisation abgewickelt.
+
+:::info Separate Organisation
+Wenn du bereits konventioneller Kunde bei uns im mStudio bist,
+kann es von Vorteil sein, eine separate Organisation für die Contribution zu erstellen,
+um die beiden Geschäftsbereiche zu trennen und Berechtigungen einfacher abzugrenzen.
+Dies ist jedoch keine Pflicht.
+:::
+
+Um Contributor zu werden, musst du in deiner Organisation einen Vertragspartner hinterlegen.
+
+![Vertragspartner hinzufügen](/img/contribution/getting-started-guide/add-contract-owner.png)
+
+![Vertragspartner konfigurieren](/img/contribution/getting-started-guide/contract-owner.png)
+
+Klicke nun auf den Button **"Contributor werden"**.
+Dadurch wird deine Organisation zu einem unverifizierten Contributor.
+
+:::info Verifizierung
+Um Extensions nicht nur für dich, sondern öffentlich bereitstellen zu können,
+musst du als Contributor verifiziert werden.
+
+Welche Informationen für die Verifizierung benötigt werden,
+wird in der [Contributor-Übersicht](../../overview/contributor) beschrieben.
+Außerdem gehen wir im [Schritt der Veröffentlichung](./publish) näher auf die Verifizierung des Contributors ein.
+:::
+
+![Contributor werden](/img/contribution/getting-started-guide/become-contributor.png)

docs/contribution/20-getting-started/03-configure-extension.mdx

@@ -0,0 +1,116 @@
+---
+title: Konfiguration der Extension
+---
+
+[//]: # "TODO man vs du, imperative mood vs passive voice"
+
+## Extension registrieren
+
+Sobald du Contributor bist, kannst du eine Extension im mStudio angelegt werden.
+Dazu muss innerhalb der Organisation der **"Entwicklung" Tab** aufgerufen werden und über den **"Anlegen" Button** eine neue Extension registriert werden.
+Zu diesem Zeitpunkt muss nur ein **Name** eingetragen werden. Dieser kann auch **nachträglich geändert werden**.
+
+Extension Namen müssen **eindeutig** sein.
+Für Entwicklungs- und Produktivzwecke empfiehlt es sich, getrennte Extensions anzulegen.
+Entwicklungs-Extensions können beispielsweise mit "(DEV)" im Namen gekennzeichnet werden.
+
+:::info Lebenszyklus von Extensions
+Extensions sind erst im Marktplatz **sichtbar**, wenn sie **veröffentlicht** wurden.
+Deswegen können problemlos für eigene Entwicklungsprozesse Entwicklungs- bzw. Staging-Extensions angelegt werden.
+Weitere Informationen zum Lebenszyklus von Extensions sind im [Extension Konzept](../../overview/extensions#lifecycle-of-an-extension) erklärt.
+:::
+
+![Extension registrieren](/img/contribution/getting-started-guide/register-extension.png)
+
+## Setzen des Extension Context
+
+Für jede Extension muss festgelegt werden, in **welchem Kontext** sie **installierbar** sein soll.
+Zur Auswahl stehen **Organisation** und **Projekt**.
+Die Reference Extension ist als Projekt-Extension gebaut.
+
+Im **Tab "Berechtigungen"** muss also in der Sektion **Extension Context** auf **Bearbeiten** geklickt werden.
+Nun wird **Projekt** gewählt und gespeichert.
+
+:::info Wahl des Extension Context
+Die Reference Extension ist als Projekt-Extension gebaut.
+Es ergibt jedoch nicht für jede Extension-Idee sinn, sie als Projekt-Extension zu implementieren.
+
+Welche Auswirkungen die Wahl hat und welche Faktoren für die Wahl entscheidend sind, haben wir im ["Wie wähle ich den richtigen Extension Context?"-Guide](../../how-to/choose-a-context) beschrieben.
+:::
+
+![Extension Context](/img/contribution/getting-started-guide/extension-context.png)
+
+## Berechtigungen konfigurieren
+
+Die Reference Extension ruft Informationen über den User und das Projekt, in dem sie installiert ist, ab.
+Außerdem bietet sie die Möglichkeit, den Namen des Projekts anzupassen.
+Um dazu in der Lage zu sein, müssen für die Extension Berechtigungen in Form von Scopes konfiguriert werden.
+Das muss immer gemacht werden, wenn Extensions auf die mStudio API zugreifen wollen.
+
+Genauso wie der Extension Context werden auch die Berechtigungen im **Tab "Berechtigungen"** konfiguriert.
+Dazu muss in der entsprechende Sektion auf "Bearbeiten" geklickt werden.
+Wir stellen nun **Projekt lesen** und **schreiben** sowie **Benutzer lesen** ein.
+
+:::info Verfügbare Scopes
+Im [Guide zu Scopes](../../overview/concepts/scopes) haben wir ausführlicher beschrieben, welche Scopes verfügbar sind und wie der richtige Scope identifiziert werden kann.
+Wenn du Schwierigkeiten damit hast, den richtigen Scope zu finden oder dein Scope fehlt, komm gerne auf uns zu.
+Wir unterstützen dich gerne dabei.
+:::
+
+![Berechtigungen einstellen](/img/contribution/getting-started-guide/scopes.png)
+
+## Extension Secret generieren
+
+Für die Authentifizierung von Frontend Fragmenten wird ein Secret benötigt.
+Dieses Secret kann wie der Extension Context und die Scopes im **"Berechtigungen"** Tab generiert werden.
+Nach dem Generieren wird dir das Secret **einmalig** angezeigt.
+Merke es dir an einem sicheren Ort für die Konfiguration der Reference Extension.
+
+:::info Extension Secret und Extension Instance Secret
+Ein Extension Secret ist nicht das gleiche wie ein Extension Instance Secret.
+Während das Extension Secret für die gesamte Extension gilt und einmalig für eine Extension ist,
+werden Extension Instances für jede einzelne Instance, sprich Installation einer Extension, ausgestellt.
+:::
+
+:::warning Generieren eines neuen Secrets
+Du kannst dir jederzeit ein neues Secret für deine Extension ausstellen lassen.
+Damit deine Extension weiterhin funktioniert, wird das alte Secret nicht sofort,
+sondern erst nach 24h invalidiert.
+Das neue Secret muss also innerhalb von 24h in der Extension hinterlegt werden,
+damit die Extension nicht ihre Fähigkeit verliert, auf die mStudio API zuzugreifen.
+
+Wenn du das neue Secret in der Extension hinterlegt hast,
+kannst du das alte auch schon früher händisch invalidieren.
+:::
+
+## Konfigurieren der Frontend-URL
+
+Die Reference Extension verwendet ein **Frontend Fragment**.
+Das bedeutet, sie implementiert ein Frontend, dass nahtlos in das mStudio integriert werden soll.
+
+:::info Frontend Fragment vs. External Frontend
+Frontend Fragmente sind nicht die einzige Möglichkeit, ein Frontend für eine Extension anzubieten.
+Wenn die Anforderungen an Frontend Fragmenten für dich zu restriktiv sind oder nicht zu deinem Anwendungsfall geeignet sind,
+gibt es auch die Möglichkeit, ein externes Frontend zu implementieren.
+
+Die Eigenschaften und Unterschiede zwischen Frontend Fragmenten und externen Frontends sind im [Konzept zur Frontend Entwicklung](../../overview/concepts/frontend-development) erklärt
+:::
+
+Um die URL für das Frontend Fragment der Reference Extension einzustellen, muss im **Tab "Frontend"** der Extension in der Sektion zu **Frontend Fragments** auf **Hinzufügen** geklickt werden.
+
+![Frontend Fragment hinzufügen](/img/contribution/getting-started-guide/frontend-fragments.png)
+
+Für ein Frontend Fragment muss ein **Ankerpunkt** gewählt werden.
+Dieser bestimmt, an welcher Stelle das Frontend deiner Extension eingebunden werden soll.
+Die Reference Extension ist gebaut, um an dem Ankerpunkt `/projects/project/menu/section/extensions/item` eingehangen zu werden,
+also als Menüpunkt innerhalb eines Projekts.
+
+Für den Ankerpunkt muss außerdem ein **Anzeigename** definiert werden.
+Dieser bestimmt bspw. bei Ankerpunkten, die als Menüpunkte fungieren, wie der Menüpunkt heißt.
+Für Sektionen bestimmt der Anzeigename die Überschrift der Sektion.
+
+Schließlich muss eine **URL** angegeben werden.
+Für die in Entwicklung befindliche Extension kann hier auch eine auf dem **lokalen Client erreichbare Adresse** eingegeben werden.
+Da die Reference Extension Standardmäßig auf Port 3000 läuft, fügen wir hier `http://localhost:3000` ein.
+
+![Konfiguration des Frontend Fragments](/img/contribution/getting-started-guide/frontend-fragment-configuration.png)