diff --git a/.gitignore b/.gitignore index d2363495..85bb2101 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,8 @@ npm-debug.log* yarn-debug.log* yarn-error.log* +/tmp + # Generated by the build process /sidebar.reference.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4dcc2ff3..488838f4 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/docs/contribution/20-glossary.mdx b/docs/contribution/10-glossary.mdx similarity index 98% rename from docs/contribution/20-glossary.mdx rename to docs/contribution/10-glossary.mdx index 1cf12332..a706d0d2 100644 --- a/docs/contribution/20-glossary.mdx +++ b/docs/contribution/10-glossary.mdx @@ -1,5 +1,6 @@ --- title: Glossary +sidebar_position: 2 --- ## Contributor diff --git a/docs/contribution/20-getting-started/02-become-contributor.mdx b/docs/contribution/20-getting-started/02-become-contributor.mdx new file mode 100644 index 00000000..c5e48b3a --- /dev/null +++ b/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) diff --git a/docs/contribution/20-getting-started/03-configure-extension.mdx b/docs/contribution/20-getting-started/03-configure-extension.mdx new file mode 100644 index 00000000..553d7a26 --- /dev/null +++ b/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) diff --git a/docs/contribution/20-getting-started/04-reference-extension.mdx b/docs/contribution/20-getting-started/04-reference-extension.mdx new file mode 100644 index 00000000..e9048871 --- /dev/null +++ b/docs/contribution/20-getting-started/04-reference-extension.mdx @@ -0,0 +1,202 @@ +--- +title: Reference Extension +--- + +[//]: # "TODO man vs du, imperative mood vs passive voice" + +## Die Reference Extension + +Die [Reference Extension](https://github.com/mittwald/reference-extension) ist eine umfassende Beispiel-Extension, +die alle wichtigen Features für die Entwicklung von Extensions, die sich direkt in das mStudio integrieren, demonstriert. +Sie dient als praktische Vorlage und Lernressource für Entwickler. + +### Idee und Motivation + +Die Reference Extension wurde entwickelt, um: + +- **Best Practices** für Extension-Entwicklung zu zeigen +- Alle wichtigen **Marketplace-Konzepte** praktisch zu demonstrieren +- Die Integration mit der mittwald API und dem mStudio zu illustrieren +- Als **Ausgangspunkt** für eigene Extension-Projekte zu dienen + +Die Extension ist vollständig dokumentiert und kann als Template verwendet werden, um eigene Extensions zu entwickeln. +Der Code ist so strukturiert, dass er leicht verstanden, angepasst und erweitert werden kann. + +### Technologischer Stack + +Die Reference Extension verwendet moderne Web-Technologien, die auch für die Entwicklung eigener Extensions empfohlen werden: + +**Frontend:** + +- **[React 19](https://react.dev/)** - Für die Entwicklung der Benutzeroberfläche +- **[TanStack Router & Query](https://tanstack.com/)** - Routing und State Management +- **[@mittwald/flow-remote-react-components](https://mittwald.github.io/flow/)** - UI-Framework, das mit Frontend Fragmenten kompatibel ist +- **[React Ghostmaker](https://github.com/mittwald/react-ghostmaker)** - Server Function Abstraktion + +**Backend:** + +- **[TanStack Start](https://tanstack.com/start/latest)** - Full-stack React Framework +- **[Drizzle ORM](https://orm.drizzle.team/)** - Typsichere Datenbankoperationen mit PostgreSQL +- **[@mittwald/api-client](https://www.npmjs.com/package/@mittwald/api-client)** - Client für die mittwald API +- **[@weissaufschwarz/mitthooks](https://www.npmjs.com/package/@weissaufschwarz/mitthooks)** - Webhook-Verarbeitung + +**Development Tools:** + +- **[Vite](https://vite.dev/)** - Schnelles Build-Tool +- **[Biome](https://biomejs.dev/)** - Linting & Formatting +- **[Vitest](https://vitest.dev/)** - Unit Testing Framework + +### Implementierte Konzepte des mStudio Marktplatzes + +Die Reference Extension demonstriert alle wichtigen Konzepte, die für die Entwicklung von Extensions, die direkt im mStudio eingebunden werden sollen, relevant sind: + +[//]: # "TODO Hinweis auf *nicht* implementierte, aber wichtige Konzepte: API client mit model Abstraktion" + +**1. Lifecycle Webhooks** + +- Verarbeitung von Lifecycle Events (create, update, remove), um einen State über bestehende Extension Instances aufbauen zu können +- Speicherung der Instance-Daten in eigener Datenbank +- Validierung der Webhook Signatur, um Missbrauch zu verhindern + +Weitere Informationen zum Zweck und der Funktionsweise von Lifecycle Webhooks können im [Konzeptdokument zu Lifecycle Webhooks](../../overview/concepts/lifecycle-webhooks) nachgelesen werden. + +**2. Frontend Fragments** + +- Rendering von UI-Komponenten im mStudio via Remote DOM +- Integration als Menüeintrag im Projekt-Kontext +- Verwendung des Anchor Points: `/projects/project/menu/section/extensions/item` + +Im ["Wie man ein Frontend-Fragment entwickelt"](../../how-to/develop-frontend-fragment)-Guide findest du detailiertere Informationen zur Funktionsweise von Frontend Fragmenten und dem Remote-DOM. + +:::info Wichtiger Hinweis zu Frontend Fragments +Um Frontend direkt in das mStudio integrieren zu können, muss ein Remote DOM bereit gestellt werden. +Das Bootstrapping der Reference Extension übernimmt das für dich. +Das Remote DOM im mStudio erfordert die Verwendung von **Flow Design System Komponenten**. +Standard HTML-Elemente wie `
` oder `