Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add description of extension lifecycle #387

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/contribution/30-overview/1-extensions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,48 @@ Optionally, an extension may define an external frontend that functions as an en
You configure the external frontend as a URL, for which you may use templating.
For more information, see [templating of configuration values](../concepts/templating) and [lifecycle webhook concept](../concepts/lifecycle-webhooks).

## Lifecycle of an Extension

After registering an Extension the verification can be requested.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get that this is a high-level description of the whole process; but is there a more detailed description of the whole process (including API calls and such) somewhere that we can link here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not yet, unfortunately.

The routes are currently beeing beautified before we publish them.

To do so a unique name has to be set.
Also the scopes, context and support-information have to be set.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
If your extension is not free the webhookUrls are also required.

The verification can be aborted by the contributor.

The extension will now be reviewed by mittwald and verified.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
If everything checks out and no feedback is provided the extension can be published.
Only the contributor can publish the extension.

### After Publication

The extension can be withdrawn again by the contributor.
This prevents new ExtensionInstances from beeing created and disables already existing instances.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
This can be useful for performing maintenance.
Afterwards the Extension can be published again without requesting a new verification.

### Changing the Extension

Changes of the scopes or the webhookUrls need to be verified by mittwald.
After these changes have been accepted the changes apply instantly.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved

The context of an extension can only be changed before the initial verification has been requested.
During the development of the extension the context can be changed freely.
This will remove all extension-instances.

### When can extension instances be added to a context

At least the context has to be set to add an extension to a context.
Before the publishing of an extension only the contributor can create instances in their own organization or projects.
Afterward everyone can create extension-instances.

### Deletion of an Extension

A graceful deletion of the extension can be realized through defining a deprecation.
The Deprecation defines a shut down date as well as a successor.

The deletion of the Extension is asynchronous because all Extension-Instances must be removed beforehand.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is inconsistent with the german translation ("Die Löschung der Extension passiert asynchron, weil alle Extension-Instances vorab gelöscht werden.").

The original sentence ("must be removed") implies that some kind of action is required (either from the contributor, or from the extension users) to remove existing extension instances, whereas the passive phrasing in the german version implies that this is done by the system.

Which is it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the german version is correct. That concept changed while this was worked on.
I'm going to correct this.


## Versioning of Extensions

The mStudio does not provide a concept for the versioning of extensions.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,48 @@ Das externe Frontend wird als URL angegeben und kann getemplated werden.
Siehe dazu auch [Templating von Konfigurationswerten](../concepts/templating).
Für weitere Informationen zum External Frontend siehe [External Frontend Konzept](../concepts/external-frontend).

## Lebenszyklus einer Extension

Nachdem eine Extension registriert wurde kann die Verifizierung beantragt werden.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
Dafür muss ein einzigartiger Name gesetzt sein.
Die Scopes, der Kontexts sowie Support-Informationen müssen ebenfalls gesetzt sein.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
Wenn die Extension nicht kostenlos angeboten werden soll werden zudem WebhookURLs benötigt.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved

Die Verifizierung kann wieder vom Contributor abgebrochen werden.

Die Extension wird nun von mittwald geprüft und im Anschluss zur veröffentlichung freigegeben.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
Nur ein Contributor kann eine Extension veröffentlichen.

### Nach der Veröffentlichung

Nach der Veröffentlichung kann eine Extension wieder zurück gezogen werden.
Dadurch werden die bestehenden Instances der Extension deaktiviert.
Dies kann nützlich sein um Wartungen durch zu führen.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved

Die Extension kann ohne erneute Verifizierung wieder veröffentlicht werden.

### Änderungen an der Extension

Änderungen an den Scopes und den WebhookURLs bedürfen einer erneuten Verifizierung durch mittwald.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
Mit der Bestätigung dieser Änderungen werden sie automatisch angewendet.

Der Context einer Extension kann nach dem Anfragen der Verifizierung nicht mehr geändert werden.
Während der Entwicklung der Extension kann der Context frei geändert werden.
Dabei werden alle Extension-Instances gelöscht.

### Wann kann wer die Extension zu einem Context hinzufügen?

Es muss mindestens der Context einer Extension gesetzt sein.
Vor der Veröffentlichung kann die Extension nur zu Kontexten des Kontributors selbst hinzugefügt werden.
Danach kann jeder die Extension zu Kontexten hinzufügen.

### Löschung der Extension

Um eine Extension schonend zu löschen kann eine Deprecation-Phase definiert werden.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved
Hier kann ein Enddatum und ein Nachfolger für die extension gewählt werden.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved

Die löschung der Extension passiert asynchron, weil alle Extension-Instances vorab gelöscht werden.
tdellmann marked this conversation as resolved.
Show resolved Hide resolved

## Versionierung von Extensions

Das mStudio sieht kein Konzept für die Versionierung von Extensions vor.
Expand Down
Loading