Merge branch 'master' into contributor-documentation

.prettierrc.json

@@ -3,6 +3,7 @@
     {
       "files": ["*.md", "*.mdx"],
       "options": {
+
         "parser": "mdx",
         "printWidth": 80,
         "proseWrap": "preserve"

CONTRIBUTING.md

@@ -25,9 +25,31 @@ You can use the following commands to build this project locally:
 
 ## How-Tos
 
+### Working with the changelog
+
+#### Adding a new changelog entry
+
+The changelog is built using [Docusaurus' blog feature][docu-blog]. You can add a new changelog entry by creating a new markdown file in the `changelog/` directory. The file name should follow the pattern `YYYY-MM-DD-<name>.mdx`. The file should contain a frontmatter section with the following fields:
+
+```yaml
+title: Example changelog entry
+authors: your-name # see changelog/authors.yml
+tags: [apiv2] # see changelog/tags.yml
+```
+
+#### Automatic API changelog entries
+
+There is also a Gitlab CI job that will automatically create a changelog entry each day when the OpenAPI specification changed (both v1 and v2 are checked for changes). This job will create a new changelog entry in the `changelog/` directory with the name `YYYY-MM-DD-api-changes-vX.mdx`. To track the API changes, the _last_ OpenAPI specification is saved in the `generator/specs` directory, which will then be compared to the _current_ OpenAPI specification. The comparison is done using the [`oasdiff` tool](https://www.oasdiff.com).
+
+To run the automatic changelog generation locally, you can run the `npm run generate:changelog` command. Note that the changelog generator relies on some AI features for text generation, to you will need a valid OpenAI API key in the `OPENAI_API_KEY` environment variable.
+
+#### Customizing generated changelog entries
+
+Automatically generated changelog entries will **NOT** be changed after they are created (they are identified uniquely by the date and the affected API version). This means that you (as a developer) are free to edit the automatically generated changelog entries to your liking (pay special attention to the AI-generated summary, which may or may not be correct).
+
 ### Updating translation files
 
-Translation of components is done using [Docuraurus' built-in translation file handling][docu-i18n]. To update the translation files, you can use the following steps:
+Translation of components is done using [Docusaurus' built-in translation file handling][docu-i18n]. To update the translation files, you can use the following steps:
 
 ```
 $ npm run docusaurus write-translations
@@ -50,5 +72,6 @@ The usage examples for OpenAPI operations are generated from the OpenAPI specifi
 [mdx]: https://mdxjs.com
 [docu-md]: https://docusaurus.io/docs/markdown-features
 [docu-i18n]: https://docusaurus.io/docs/i18n/introduction
+[docu-blog]: https://docusaurus.io/docs/blog
 [docs-en]: https://github.com/mittwald/developer-portal/tree/master/docs
-[docs-de]: https://github.com/mittwald/developer-portal/tree/master/i18n/de/docusaurus-plugin-content-docs/current
+[docs-de]: https://github.com/mittwald/developer-portal/tree/master/i18n/de/docusaurus-plugin-content-docs/current

changelog/2024-07-29-api-changelog.mdx

@@ -0,0 +1,11 @@
+---
+title: API changelog starting August, 2024
+authors: mhelmich
+tags:
+  - apiv2
+  - apiv1
+---
+
+This changelog will contain all developer-relevant changes to the mittwald v1 and v2 API, and the mittwald cloud platform starting August, 2024. The API changes are based on the diff between the OpenAPI schemas of the two versions, using [oasdiff](https://www.oasdiff.com).
+
+<!-- truncate -->

changelog/2024-07-29-api-changes-v2.mdx

@@ -0,0 +1,99 @@
+---
+title: Breaking (!) API changes for v2 API, July 29, 2024
+authors:
+  - machine
+tags:
+  - apiv2
+  - breaking
+  - Domain
+  - App
+  - Article
+  - User
+  - Contract
+  - Marketplace
+  - Conversation
+  - Cronjob
+  - Customer
+  - Mail
+  - File
+  - Relocation
+  - Database
+  - Notification
+  - Page Insights
+  - Backup
+  - Project
+  - Project File System
+  - SSH/SFTP User
+---
+
+import OperationHint from "@site/src/components/OperationHint";
+import OperationLink from "@site/src/components/OperationLink";
+
+This document contains a machine-generated summary of the API changes for July 29, 2024. The API changes are based on the diff between the OpenAPI schemas of the two versions.
+
+{/* truncate */}
+
+:::caution Breaking changes
+
+This document contains changes that can under certain circumstances be considered breaking. Please review the changes carefully.
+
+While we generally strive to avoid breaking changes in accordance with our [API stability guarantees](../../../../../docs/v2/api/stability), we occasionally might perform changes that would be considered breaking in the strictest sense of the term, but we do not consider as breaking in a practical sense. We will always provide ample notice and documentation for such changes.
+
+:::
+
+## Summary
+
+- A `429 Too Many Requests` status code has been added to the specification of _every_ API endpoint. This status code is returned when the rate limit is exceeded. The rate limiting feature is not new, but the documentation has been updated to reflect this behavior. See the section on [API ratelimiting](../../../../../docs/v2/api/intro#rate-limiting) for more information.
+- Changed the way the request body of the <OperationLink operation="ingress-update-ingress-tls" apiVersion="v2" /> endpoint is defined (might potentially cause breaking changes in generated client code).
+
+## Detailed changes
+
+### Changes in "Update the tls settings of an Ingress"
+
+- ⚠️ **Breaking:** replaced '#/components/schemas/de.mittwald.v1.ingress.TlsAcme, #/components/schemas/de.mittwald.v1.ingress.TlsCertificate' from the request body 'oneOf' list, and substituted inline schemas. Note that this is not a breaking change when you are using the API directly, but it might cause breaking changes in code generated from the OpenAPI schema.
+
+For details, refer to the <OperationLink operation="ingress-update-ingress-tls" apiVersion="v2" /> endpoint.
+
+### Changes to _all_ API endpoints
+
+- added the non-success response with the status '429'
+
+### Changes in "Create an Order"
+
+- removed the non-success response with the status '403'
+
+For details, refer to the <OperationLink operation="order-create-order" apiVersion="v2" /> endpoint.
+
+### Changes in "Register with email and password"
+
+- removed the non-success response with the status '403'
+
+For details, refer to the <OperationLink operation="user-register" apiVersion="v2" /> endpoint.
+
+### Changes in "Resend the mail address verification email"
+
+- removed the non-success response with the status '403'
+
+For details, refer to the <OperationLink operation="deprecated-user-resend-verification-email" apiVersion="v2" /> endpoint.
+
+### Changes in "Initialize password reset process"
+
+- removed the non-success response with the status '403'
+
+For details, refer to the <OperationLink operation="deprecated-user-init-password-reset" apiVersion="v2" /> endpoint.
+
+### Changes in "Initialize password reset process"
+
+- removed the non-success response with the status '403'
+
+For details, refer to the <OperationLink operation="user-init-password-reset" apiVersion="v2" /> endpoint.
+
+## Client package releases
+
+### mittwald PHP SDK release release v2.1.42
+
+The mittwald PHP SDK v2.1.42 has been released, which reflects the changes in the API. You can find the release notes [here](https://github.com/mittwald/api-client-php/releases/tag/v2.1.42).
+
+### mittwald Javascript SDK release v4.42.0
+
+The mittwald JavaScript SDK v4.42.0 has been released, which reflects the changes in the API. You can find the release notes [here](https://github.com/mittwald/api-client-js/releases/tag/4.42.0).

changelog/2024-08-02-api-changes-v2.mdx

@@ -0,0 +1,54 @@
+---
+title: API changes for v2 API, August 2, 2024
+authors:
+  - machine
+tags:
+  - apiv2
+  - Marketplace
+  - Conversation
+
+---
+
+import OperationHint from "@site/src/components/OperationHint";
+import OperationLink from "@site/src/components/OperationLink";
+
+This document contains a machine-generated summary of the API changes for August 2, 2024.
+The API changes are based on the diff between the OpenAPI schemas of the two versions.
+
+{/* truncate */}
+
+
+
+## Summary
+
+
+- A new endpoint has been added for the operation `POST` with the operation ID `extension-dry-run-webhook` at the path `/v2/contributors/{contributorId}/extensions/{extensionId}/extension-instances/{extensionInstanceId}/actions/dry-run/{webhookKind}`.
+- The `sharedWith` request property for the operation `POST` with the operation ID `conversation-create-conversation` at the path `/v2/conversations` has been updated to include 'subschema #4' in its `oneOf` list.
+
+_Disclaimer: This summary is AI-generated. If you find any discrepancies, please refer to the detailed changes below._
+
+
+## Detailed changes
+
+
+
+### Changes in "Dry run a webhook with random or given values"
+
+
+- endpoint added
+
+
+For details, refer to the <OperationLink operation="extension-dry-run-webhook" apiVersion="v2" /> endpoint.
+
+
+
+### Changes in "Create a conversation"
+
+
+- added 'subschema #4' to the 'sharedWith' request property 'oneOf' list
+
+
+For details, refer to the <OperationLink operation="conversation-create-conversation" apiVersion="v2" /> endpoint.
+
+
+