docs: change from detecting version to since tag (medusajs#13127)

shahednasser · web-flow · commit 522fc12d7ac0 · 2025-08-01T18:22:42.000+03:00
* update everything from version to since

* update events

* regenerate oas
diff --git a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/Events/index.tsx b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/Events/index.tsx
@@ -108,9 +108,9 @@ const TagsOperationDescriptionSectionEvent = ({
             ) : (
               <Badge variant="orange">Deprecated</Badge>
             ))}
-          {event.version && (
-            <Tooltip text={`This event is emitted since v${event.version}`}>
-              <Badge variant="blue">v{event.version}</Badge>
+          {event.since && (
+            <Tooltip text={`This event is emitted since v${event.since}`}>
+              <Badge variant="blue">v{event.since}</Badge>
             </Tooltip>
           )}
         </div>
diff --git a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx
@@ -78,12 +78,12 @@ const TagsOperationDescriptionSection = ({
             badgeClassName="ml-0.5"
           />
         )}
-        {operation["x-version"] && (
+        {operation["x-since"] && (
           <Tooltip
-            text={`This API route is available since v${operation["x-version"]}`}
+            text={`This API route is available since v${operation["x-since"]}`}
           >
             <Badge variant="blue" className="ml-0.5">
-              v{operation["x-version"]}
+              v{operation["x-since"]}
             </Badge>
           </Tooltip>
         )}
diff --git a/www/apps/api-reference/specs/admin/openapi.full.yaml b/www/apps/api-reference/specs/admin/openapi.full.yaml
@@ -15024,7 +15024,7 @@ paths:
           $ref: '#/components/responses/500_error'
       x-workflow: deleteDraftOrdersWorkflow
       x-events: []
-      x-version: 2.8.4
+      x-since: 2.8.4
   /admin/draft-orders/{id}/convert-to-order:
     post:
       operationId: PostDraftOrdersIdConvertToOrder
@@ -22738,7 +22738,7 @@ paths:
             ```
           description: Emitted when an order edit request is canceled.
           deprecated: false
-          version: 2.8.0
+          since: 2.8.0
   /admin/order-edits/{id}/confirm:
     post:
       operationId: PostOrderEditsIdConfirm
@@ -22812,7 +22812,7 @@ paths:
             ```
           description: Emitted when an order edit request is confirmed.
           deprecated: false
-          version: 2.8.0
+          since: 2.8.0
   /admin/order-edits/{id}/items:
     post:
       operationId: PostOrderEditsIdItems
@@ -23208,7 +23208,7 @@ paths:
             ```
           description: Emitted when an order edit is requested.
           deprecated: false
-          version: 2.8.0
+          since: 2.8.0
   /admin/order-edits/{id}/shipping-method:
     post:
       operationId: PostOrderEditsIdShippingMethod
@@ -33277,7 +33277,7 @@ paths:
           $ref: '#/components/responses/500_error'
       x-workflow: importProductsAsChunksWorkflow
       x-events: []
-      x-version: 2.8.5
+      x-since: 2.8.5
   /admin/products/imports/{transaction_id}/confirm:
     post:
       operationId: PostProductsImportsTransaction_idConfirm
@@ -33335,7 +33335,7 @@ paths:
           $ref: '#/components/responses/invalid_request_error'
         '500':
           $ref: '#/components/responses/500_error'
-      x-version: 2.8.5
+      x-since: 2.8.5
   /admin/products/{id}:
     get:
       operationId: GetProductsId
@@ -48956,7 +48956,7 @@ paths:
           $ref: '#/components/responses/invalid_request_error'
         '500':
           $ref: '#/components/responses/500_error'
-      x-version: 2.8.0
+      x-since: 2.8.0
   /admin/tax-rates:
     get:
       operationId: GetTaxRates
diff --git a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}.yaml b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}.yaml
@@ -199,4 +199,4 @@ delete:
       $ref: ../components/responses/500_error.yaml
   x-workflow: deleteDraftOrdersWorkflow
   x-events: []
-  x-version: 2.8.4
+  x-since: 2.8.4
diff --git a/www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}.yaml b/www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}.yaml
@@ -75,4 +75,4 @@ delete:
         ```
       description: Emitted when an order edit request is canceled.
       deprecated: false
-      version: 2.8.0
+      since: 2.8.0
diff --git a/www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}_confirm.yaml b/www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}_confirm.yaml
@@ -56,4 +56,4 @@ post:
         ```
       description: Emitted when an order edit request is confirmed.
       deprecated: false
-      version: 2.8.0
+      since: 2.8.0
diff --git a/www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}_request.yaml b/www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}_request.yaml
@@ -56,4 +56,4 @@ post:
         ```
       description: Emitted when an order edit is requested.
       deprecated: false
-      version: 2.8.0
+      since: 2.8.0
diff --git a/www/apps/api-reference/specs/admin/paths/admin_products_imports.yaml b/www/apps/api-reference/specs/admin/paths/admin_products_imports.yaml
@@ -47,4 +47,4 @@ post:
       $ref: ../components/responses/500_error.yaml
   x-workflow: importProductsAsChunksWorkflow
   x-events: []
-  x-version: 2.8.5
+  x-since: 2.8.5
diff --git a/www/apps/api-reference/specs/admin/paths/admin_products_imports_{transaction_id}_confirm.yaml b/www/apps/api-reference/specs/admin/paths/admin_products_imports_{transaction_id}_confirm.yaml
@@ -44,4 +44,4 @@ post:
       $ref: ../components/responses/invalid_request_error.yaml
     '500':
       $ref: ../components/responses/500_error.yaml
-  x-version: 2.8.5
+  x-since: 2.8.5
diff --git a/www/apps/api-reference/specs/admin/paths/admin_tax-providers.yaml b/www/apps/api-reference/specs/admin/paths/admin_tax-providers.yaml
@@ -192,4 +192,4 @@ get:
       $ref: ../components/responses/invalid_request_error.yaml
     '500':
       $ref: ../components/responses/500_error.yaml
-  x-version: 2.8.0
+  x-since: 2.8.0
diff --git a/www/apps/api-reference/specs/store/openapi.full.yaml b/www/apps/api-reference/specs/store/openapi.full.yaml
@@ -1360,7 +1360,7 @@ paths:
             ```
           description: Emitted when the customer in the cart is transferred.
           deprecated: false
-          version: 2.8.0
+          since: 2.8.0
   /store/carts/{id}/gift-cards:
     post:
       operationId: PostCartsIdGiftCards
@@ -8845,7 +8845,7 @@ paths:
             ```
           description: Emitted when a return is marked as received.
           deprecated: false
-      x-version: 2.8.0
+      x-since: 2.8.0
   /store/shipping-options:
     get:
       operationId: GetShippingOptions
diff --git a/www/apps/api-reference/specs/store/paths/store_carts_{id}_customer.yaml b/www/apps/api-reference/specs/store/paths/store_carts_{id}_customer.yaml
@@ -87,4 +87,4 @@ post:
         ```
       description: Emitted when the customer in the cart is transferred.
       deprecated: false
-      version: 2.8.0
+      since: 2.8.0
diff --git a/www/apps/api-reference/specs/store/paths/store_returns.yaml b/www/apps/api-reference/specs/store/paths/store_returns.yaml
@@ -67,4 +67,4 @@ post:
         ```
       description: Emitted when a return is marked as received.
       deprecated: false
-  x-version: 2.8.0
+  x-since: 2.8.0
diff --git a/www/apps/book/app/learn/update/page.mdx b/www/apps/book/app/learn/update/page.mdx
@@ -107,7 +107,7 @@ npx medusa db:migrate
 In the Medusa codebase, our team uses the following [TSDoc](https://tsdoc.org/) tags to indicate changes made in the latest version for a specific piece of code:
 
 - `@deprecated`: Indicates that a piece of code is deprecated and will be removed in a future version. The tag's message will include details on what to use instead. However, our updates are always backward-compatible, allowing you to update your codebase at your own pace.
-- `@version`: Indicates the version when a piece of code was available from. A piece of code that has this tag will only be available starting from the specified version.
+- `@since`: Indicates the version when a piece of code was available from. A piece of code that has this tag will only be available starting from the specified version.
 
 ---
 
diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
@@ -23247,7 +23247,7 @@ npx medusa db:migrate
 In the Medusa codebase, our team uses the following [TSDoc](https://tsdoc.org/) tags to indicate changes made in the latest version for a specific piece of code:
 
 - `@deprecated`: Indicates that a piece of code is deprecated and will be removed in a future version. The tag's message will include details on what to use instead. However, our updates are always backward-compatible, allowing you to update your codebase at your own pace.
-- `@version`: Indicates the version when a piece of code was available from. A piece of code that has this tag will only be available starting from the specified version.
+- `@since`: Indicates the version when a piece of code was available from. A piece of code that has this tag will only be available starting from the specified version.
 
 ***
 
diff --git a/www/packages/types/src/openapi.ts b/www/packages/types/src/openapi.ts
@@ -23,7 +23,7 @@ export type Operation = OpenAPIV3.OperationObject<{
   "x-workflow"?: string
   "x-sidebar-summary"?: string
   "x-events"?: OasEvents[]
-  "x-version"?: string
+  "x-since"?: string
   "x-deprecated_message"?: string
   "x-badges"?: {
     text: string
@@ -149,5 +149,5 @@ export type OasEvents = {
   description?: string
   deprecated?: boolean
   deprecated_message?: string
-  version?: string
+  since?: string
 }
diff --git a/www/utils/generated/events-output.json b/www/utils/generated/events-output.json
@@ -44,7 +44,7 @@
     "workflows": [
       "transferCartCustomerWorkflow"
     ],
-    "version": "2.8.0",
+    "since": "2.8.0",
     "deprecated": false
   },
   {
@@ -227,7 +227,7 @@
     "workflows": [
       "requestOrderEditRequestWorkflow"
     ],
-    "version": "2.8.0",
+    "since": "2.8.0",
     "deprecated": false
   },
   {
@@ -239,7 +239,7 @@
     "workflows": [
       "confirmOrderEditRequestWorkflow"
     ],
-    "version": "2.8.0",
+    "since": "2.8.0",
     "deprecated": false
   },
   {
@@ -251,7 +251,7 @@
     "workflows": [
       "cancelBeginOrderEditWorkflow"
     ],
-    "version": "2.8.0",
+    "since": "2.8.0",
     "deprecated": false
   },
   {
diff --git a/www/utils/generated/oas-output/operations/admin/delete_admin_draft-orders_[id].ts b/www/utils/generated/oas-output/operations/admin/delete_admin_draft-orders_[id].ts
@@ -57,7 +57,7 @@
  *     $ref: "#/components/responses/500_error"
  * x-workflow: deleteDraftOrdersWorkflow
  * x-events: []
- * x-version: 2.8.4
+ * x-since: 2.8.4
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/admin/delete_admin_order-edits_[id].ts b/www/utils/generated/oas-output/operations/admin/delete_admin_order-edits_[id].ts
@@ -90,7 +90,7 @@
  *       ```
  *     description: Emitted when an order edit request is canceled.
  *     deprecated: false
- *     version: 2.8.0
+ *     since: 2.8.0
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/admin/get_admin_tax-providers.ts b/www/utils/generated/oas-output/operations/admin/get_admin_tax-providers.ts
@@ -182,7 +182,7 @@
  *     $ref: "#/components/responses/invalid_request_error"
  *   "500":
  *     $ref: "#/components/responses/500_error"
- * x-version: 2.8.0
+ * x-since: 2.8.0
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_confirm.ts b/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_confirm.ts
@@ -71,7 +71,7 @@
  *       ```
  *     description: Emitted when an order edit request is confirmed.
  *     deprecated: false
- *     version: 2.8.0
+ *     since: 2.8.0
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_request.ts b/www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_request.ts
@@ -71,7 +71,7 @@
  *       ```
  *     description: Emitted when an order edit is requested.
  *     deprecated: false
- *     version: 2.8.0
+ *     since: 2.8.0
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_products_imports.ts b/www/utils/generated/oas-output/operations/admin/post_admin_products_imports.ts
@@ -69,7 +69,7 @@
  *     $ref: "#/components/responses/500_error"
  * x-workflow: importProductsAsChunksWorkflow
  * x-events: []
- * x-version: 2.8.5
+ * x-since: 2.8.5
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_products_imports_[transaction_id]_confirm.ts b/www/utils/generated/oas-output/operations/admin/post_admin_products_imports_[transaction_id]_confirm.ts
@@ -55,7 +55,7 @@
  *     $ref: "#/components/responses/invalid_request_error"
  *   "500":
  *     $ref: "#/components/responses/500_error"
- * x-version: 2.8.5
+ * x-since: 2.8.5
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/store/post_store_carts_[id]_customer.ts b/www/utils/generated/oas-output/operations/store/post_store_carts_[id]_customer.ts
@@ -97,7 +97,7 @@
  *       ```
  *     description: Emitted when the customer in the cart is transferred.
  *     deprecated: false
- *     version: 2.8.0
+ *     since: 2.8.0
  * 
 */
 
diff --git a/www/utils/generated/oas-output/operations/store/post_store_returns.ts b/www/utils/generated/oas-output/operations/store/post_store_returns.ts
@@ -85,7 +85,7 @@
  *       ```
  *     description: Emitted when a return is marked as received.
  *     deprecated: false
- * x-version: 2.8.0
+ * x-since: 2.8.0
  * 
 */
 
diff --git a/www/utils/packages/docs-generator/src/classes/kinds/default.ts b/www/utils/packages/docs-generator/src/classes/kinds/default.ts
@@ -600,16 +600,16 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
    * Retrieve information from the tags of a node.
    *
    * @param node - The node to retrieve the information from.
-   * @returns An object containing the deprecated and version tags, if available.
+   * @returns An object containing the deprecated and since tags, if available.
    */
   getInformationFromTags(node: ts.Node): {
     deprecatedTag: ts.JSDocTag | undefined
-    versionTag: ts.JSDocTag | undefined
+    sinceTag: ts.JSDocTag | undefined
     featureFlagTag: ts.JSDocTag | undefined
   } {
     const nodeComments = ts.getJSDocCommentsAndTags(node)
     let deprecatedTag: ts.JSDocTag | undefined
-    let versionTag: ts.JSDocTag | undefined
+    let sinceTag: ts.JSDocTag | undefined
     let featureFlagTag: ts.JSDocTag | undefined
 
     nodeComments.forEach((comment) => {
@@ -622,8 +622,8 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
           deprecatedTag = tag
         }
 
-        if (tag.tagName.getText() === "version") {
-          versionTag = tag
+        if (tag.tagName.getText() === "since") {
+          sinceTag = tag
         }
 
         if (tag.tagName.getText() === "featureFlag") {
@@ -634,7 +634,7 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
 
     return {
       deprecatedTag,
-      versionTag,
+      sinceTag,
       featureFlagTag,
     }
   }
diff --git a/www/utils/packages/docs-generator/src/classes/kinds/events.ts b/www/utils/packages/docs-generator/src/classes/kinds/events.ts
@@ -50,7 +50,7 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
 
         const commentsAndTags = ts.getJSDocCommentsAndTags(propertyAssignment)
         let payloadTag: ts.JSDocTag | undefined
-        let versionTag: ts.JSDocTag | undefined
+        let sinceTag: ts.JSDocTag | undefined
         let deprecatedTag: ts.JSDocTag | undefined
         let description: string | undefined
         commentsAndTags.forEach((comment) => {
@@ -67,8 +67,8 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
               payloadTag = tag
             }
 
-            if (tag.tagName.getText() === "version") {
-              versionTag = tag
+            if (tag.tagName.getText() === "since") {
+              sinceTag = tag
             }
 
             if (tag.tagName.getText() === "deprecated") {
@@ -84,7 +84,7 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
           payload: (payloadTag?.comment as string) ?? "",
           description,
           workflows,
-          version: versionTag?.comment as string,
+          since: sinceTag?.comment as string,
           deprecated: deprecatedTag !== undefined,
           deprecated_message: deprecatedTag?.comment as string,
         }
diff --git a/www/utils/packages/docs-generator/src/classes/kinds/oas.ts b/www/utils/packages/docs-generator/src/classes/kinds/oas.ts
diff --git a/www/utils/packages/docs-generator/src/types/index.d.ts b/www/utils/packages/docs-generator/src/types/index.d.ts
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/version.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/version.ts
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-events.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-events.ts
diff --git a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
diff --git a/www/utils/packages/types/lib/index.d.ts b/www/utils/packages/types/lib/index.d.ts
