https://www.eventcatalog.dev/assets/js/e7b426cc.2ed98e04.js

1/*! For license information please see e7b426cc.2ed98e04.js.LICENSE.txt */
2"use strict";(globalThis.webpackChunkeventcatalog_docs=globalThis.webpackChunkeventcatalog_docs||[]).push([[13567],{5470:(e,n,r)=>{r.d(n,{A:()=>s});const s=(0,r(46493).A)("ChevronDown",[["path",{d:"m6 9 6 6 6-6",key:"qrunsl"}]])},5904:(e,n,r)=>{r.d(n,{A:()=>s});const s=(0,r(46493).A)("FileText",[["path",{d:"M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z",key:"1rqfz7"}],["path",{d:"M14 2v4a2 2 0 0 0 2 2h4",key:"tnqrlb"}],["path",{d:"M10 9H8",key:"b1mrlr"}],["path",{d:"M16 13H8",key:"t4e002"}],["path",{d:"M16 17H8",key:"z1uh3a"}]])},11712:(e,n,r)=>{r.r(n),r.d(n,{assets:()=>c,contentTitle:()=>d,default:()=>v,frontMatter:()=>o,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"development/guides/versioning-resources","title":"Versioning resources","description":"Learn how versioning works for EventCatalog resources.","source":"@site/docs/development/guides/98-versioning-resources.md","sourceDirName":"development/guides","slug":"/development/guides/versioning-resources","permalink":"/docs/development/guides/versioning-resources","draft":false,"unlisted":false,"editUrl":"https://github.com/event-catalog/docs/tree/main/docs/development/guides/98-versioning-resources.md","tags":[],"version":"current","sidebarPosition":98,"frontMatter":{"sidebar_position":98,"keywords":["versioning","resources","EventCatalog"],"sidebar_label":"Versioning resources","title":"Versioning resources","description":"Learn how versioning works for EventCatalog resources."},"sidebar":"tutorialSidebar","previous":{"title":"Architecture Graph","permalink":"/docs/development/guides/architecture-graph"},"next":{"title":"Adding Analytics","permalink":"/docs/development/guides/adding-analytics"}}');var i=r(86070),a=r(48193),t=r(39328);const o={sidebar_position:98,keywords:["versioning","resources","EventCatalog"],sidebar_label:"Versioning resources",title:"Versioning resources",description:"Learn how versioning works for EventCatalog resources."},d=void 0,c={},l=[{value:"How versioning works",id:"how-versioning-works",level:2}

2,{value:"Create a new version",id:"create-a-new-version",level:2},{value:"Versioned URLs",id:"versioned-urls",level:2},{value:"Referencing versions",id:"referencing-versions",level:2},{value:"What can be versioned?",id:"what-can-be-versioned",level:2},{value:"Version numbers",id:"version-numbers",level:2},{value:"Versioning and changelogs",id:"versioning-and-changelogs",level:2},{value:"When to version",id:"when-to-version",level:2}];function h(e){const n={code:"code",h2:"h2",li:"li",ol:"ol",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,a.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:"EventCatalog resources can be versioned when you want to preserve how a resource looked at a point in time."}),"\n",(0,i.jsx)(n.p,{children:"Use versioning when a resource changes in a way that people may need to understand later, such as a service contract change, a message payload change, a domain boundary change, or a new major version of a system capability."}),"\n",(0,i.jsx)(n.h2,{id:"how-versioning-works",children:"How versioning works"}),"\n",(0,i.jsx)(n.p,{children:"The latest version of a resource lives in the normal resource folder."}),"\n",(0,i.jsxs)(n.p,{children:["Older versions live inside a ",(0,i.jsx)(n.code,{children:"versioned"})," folder under that resource. Each version has its own folder and its own ",(0,i.jsx)(n.code,{children:"index.mdx"})," file."]}),"\n",(0,i.jsx)(n.p,{children:"For example, a versioned service looks like this:"}),"\n",(0,i.jsx)(t.A,{items:[{name:"services",type:"folder",defaultOpen:!0,children:[{name:"Orders",type:"folder",defaultOpen:!0,children:[{name:"index.mdx",highlight:!0},{name:"versioned",type:"folder",defaultOpen:!0,children:[{name:"1.0.0",type:"folder",defaultOpen:!0,children:[{name:"index.mdx",highlight:!0}]}]}]}]}]}),"\n",(0,i.jsxs)(n.p,{children:["The root ",(0,i.jsx)(n.code,{children:"index.mdx"})," is the current version. The file in ",(0,i.jsx)(n.code,{children:"versioned/1.0.0/index.mdx"})," is the historical version."]}),"\n",(0,i.jsx)(n.h2,{id:"create-a-new-version",children:"Create a new version"}),"\n",(0,i.jsx)(n.p,{children:"To create a new version:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["Copy the current resource into a new folder under ",(0,i.jsx)(n.code,{children:"versioned/{version}"}),"."]}),"\n",(0,i.jsx)(n.li,{children:"Keep the copied file at the old version number."}),"\n",(0,i.jsx)(n.li,{children:"Update the root resource to the new version number."}),"\n",(0,i.jsx)(n.li,{children:"Update the root resource content to describe the latest state."}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["For example, before changing ",(0,i.jsx)(n.code,{children:"Orders"})," from ",(0,i.jsx)(n.code,{children:"1.0.0"})," to ",(0,i.jsx)(n.code,{children:"2.0.0"}),", copy the current file into ",(0,i.jsx)(n.code,{children:"versioned/1.0.0/index.mdx"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-md",metastring:'title="/services/Orders/versioned/1.0.0/index.mdx"',children:"---\nid: Orders\nname: Orders\nversion: 1.0.0\nsummary: Handles order placement and order history.\n---\n\n## Overview\n\nThis is the original Orders service documentation.\n"})}),"\n",(0,i.jsx)(n.p,{children:"Then update the root file:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-md",metastring:'title="/services/Orders/index.mdx"',children:"---\nid: Orders\nname: Orders\nversion: 2.0.0\nsummary: Handles order placement, order history, and order amendments.\n---\n\n## Overview\n\nThis is the latest Orders service documentation.\n"})}),"\n",(0,i.jsx)(n.h2,{id:"versioned-urls",children:"Versioned URLs"}),"\n",(0,i.jsx)(n.p,{children:"EventCatalog creates versioned pages for resources that have versions."}),"\n",(0,i.jsx)(n.p,{children:"For example:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Resource"}),(0,i.jsx)(n.th,{children:"URL"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsxs)(n.td,{children:["Latest ",(0,i.jsx)(n.code,{children:"Orders"})," service"]}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"/docs/services/Orders"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsxs)(n.td,{children:[(0,i.jsx)(n.code,{children:"Orders"})," service version ",(0,i.jsx)(n.code,{children:"1.0.0"})]}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"/docs/services/Orders/1.0.0"})})]})]})]}),"\n",(0,i.jsx)(n.p,{children:"This lets users compare the current resource with previous versions when they need historical context."}),"\n",(0,i.jsx)(n.h2,{id:"referencing-versions",children:"Referencing versions"}),"\n",(0,i.jsxs)(n.p,{children:["When one resource references another resource, you can include a ",(0,i.jsx)(n.code,{children:"version"})," field when you want to point to a specific version."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-md",metastring:'title="/services/Payments/index.mdx"',children:"---\nid: Payments\nname: Payments\nversion: 1.0.0\n\nreceives:\n  - id: OrderPlaced\n    version: 1.0.0\n---\n"})}),"\n",(0,i.jsx)(n.p,{children:"Use a specific version when the relationship depen

2ds on that version of the resource."}),"\n",(0,i.jsx)(n.p,{children:"Leave the version out when the relationship should point to the latest version."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-md",metastring:'title="/services/Payments/index.mdx"',children:"---\nid: Payments\nname: Payments\nversion: 1.0.0\n\nreceives:\n  - id: OrderPlaced\n---\n"})}),"\n",(0,i.jsx)(n.h2,{id:"what-can-be-versioned",children:"What can be versioned?"}),"\n",(0,i.jsx)(n.p,{children:"You can version the resources you document in EventCatalog, including:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Domains"}),"\n",(0,i.jsx)(n.li,{children:"Systems"}),"\n",(0,i.jsx)(n.li,{children:"Services"}),"\n",(0,i.jsx)(n.li,{children:"Messages"}),"\n",(0,i.jsx)(n.li,{children:"Schemas and specifications"}),"\n",(0,i.jsx)(n.li,{children:"Data stores"}),"\n",(0,i.jsx)(n.li,{children:"Data products"}),"\n",(0,i.jsx)(n.li,{children:"Entities"}),"\n",(0,i.jsx)(n.li,{children:"Flows"}),"\n",(0,i.jsx)(n.li,{children:"Agents"}),"\n",(0,i.jsx)(n.li,{children:"Architecture decision records"}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["The folder location changes by resource type, but the pattern is the same: keep the latest resource in the root folder and store older versions under ",(0,i.jsx)(n.code,{children:"versioned/{version}"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"version-numbers",children:"Version numbers"}),"\n",(0,i.jsx)(n.p,{children:"EventCatalog does not force a specific versioning strategy. Most teams use semantic versioning:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Version change"}),(0,i.jsx)(n.th,{children:"Use when"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:"Patch"}),(0,i.jsx)(n.td,{children:"Fixing documentation, examples, or non-behavioral details"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:"Minor"}),(0,i.jsx)(n.td,{children:"Adding fields, endpoints, resources, or capabilities in a backwards-compatible way"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:"Major"}),(0,i.jsx)(n.td,{children:"Removing or changing behavior, contracts, fields, routes, or ownership in a breaking way"})]})]})]}),"\n",(0,i.jsx)(n.p,{children:"The important part is consistency. Pick a convention your team understands and apply it across the catalog."}),"\n",(0,i.jsx)(n.h2,{id:"versioning-and-changelogs",children:"Versioning and changelogs"}),"\n",(0,i.jsx)(n.p,{children:"Versioning preserves the old state of a resource. Changelogs explain why the resource changed."}),"\n",(0,i.jsxs)(n.p,{children:["Use both when the change needs context. For example, a service can have version ",(0,i.jsx)(n.code,{children:"2.0.0"})," and a changelog entry explaining that the service started publishing a new event or removed an old endpoint."]}),"\n",(0,i.jsx)(n.h2,{id:"when-to-version",children:"When to version"}),"\n",(0,i.jsx)(n.p,{children:"Version resources when the old state still matters."}),"\n",(0,i.jsx)(n.p,{children:"Good examples include:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"A breaking API or schema change."}),"\n",(0,i.jsx)(n.li,{children:"A message contract changing."}),"\n",(0,i.jsx)(n.li,{children:"A service or system taking on a new responsibility."}),"\n",(0,i.jsx)(n.li,{children:"A domain boundary changing."}),"\n",(0,i.jsx)(n.li,{children:"A resource being replaced or deprecated."}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"You do not need to version every small documentation edit. If the change is just wording, formatting, or a small clarification, updating the current page is usually enough."})]})}function v(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(h,{...e})}):h(e)}},28464:(e,n,r)=>{r.d(n,{A:()=>s});const s=(0,r(46493).A)("Folder",[["path",{d:"M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z",key:"1kt360"}]])},39328:(e,n,r)=>{r.d(n,{A:()=>y});var s=r(30758),i=r(46493);const a=(0,i.A)("Package",[["path",{d:"M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z",key:"1a0edw"}],["path",{d:"M12 22V12",key:"d0xqtd"}],["path",{d:"m3.3 7 7.703 4.734a2 2 0 0 0 1.994 0L20.7 7",key:"yx3hmr"}],["path",{d:"m7.5 4.27 9 5.15",key:"1c824w"}]]),t=(0,i.A)("Settings",[["path",{d:"M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z",key:"1qme2f"}],["circle",{cx:"12",cy:"12",r:"3",key:"1v7zrd"}]]);var o=r(58540),d=r(78286);const c=(0,i.A)("Image",[["rect",{width:"18",height:"18",x:"3",y:"3",rx:"2",ry:"2",key:"1m3agn"}],["circle",{cx:"9",cy:"9",r:"2",key:"af1f0g"}],["path",{d:"m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21",key:"1xmnt7"}]]);var l=r(52096),h=r(5904),v=r(28464),m=r(5470);const u=(0,i.A)("ChevronRight",[["path",{d:"m9 18 6-6-6-6",key:"mthhwq"}]]),g={tree:"tree_iduJ",group:"group_XCcE",item:"item_Bswx",row:"row_E2ak",expander:"exp

2ander_WxjF",icon:"icon_YVEm",imageIcon:"imageIcon_JlF1",name:"name_vEPP",highlight:"highlight_EDAN"};var p=r(86070);function x({item:e,isFolder:n}){if(e.name.toLowerCase().includes("openapi"))return(0,p.jsx)("img",{className:g.imageIcon,src:"/img/integrations/openapi.svg",alt:"","aria-hidden":"true"});if(e.name.toLowerCase().includes("asyncapi"))return(0,p.jsx)("img",{className:g.imageIcon,src:"/img/integrations/asyncapi.svg",alt:"","aria-hidden":"true"});if(e.name.toLowerCase().includes("graphql")||e.name.toLowerCase().endsWith(".graphql"))return(0,p.jsx)("img",{className:g.imageIcon,src:"/img/integrations/graphql.svg",alt:"","aria-hidden":"true"});if(e.name.endsWith(".avsc")||e.name.endsWith(".avro"))return(0,p.jsx)("img",{className:g.imageIcon,src:"/img/integrations/avro.svg",alt:"","aria-hidden":"true"});if(e.name.endsWith(".astro"))return(0,p.jsx)("img",{className:g.imageIcon,src:"/img/integrations/astro.svg",alt:"","aria-hidden":"true"});const r=n?v.A:"package.json"===(s=e.name)?a:s.includes("config")?t:"domains"===s||"services"===s||"events"===s||"commands"===s||"queries"===s?o.A:"teams"===s||"users"===s?d.A:"public"===s||"diagrams"===s?c:s.endsWith(".json")?l.A:h.A;var s;return(0,p.jsx)(r,{className:g.icon,size:17,strokeWidth:2,"aria-hidden":"true"})}function j({item:e,depth:n=0,path:r=e.name}){const i="folder"===e.type||Boolean(e.children?.length),[a,t]=s.useState(!1!==e.defaultOpen),o=Boolean(e.children?.length),d=i&&o,c=`project-tree-${r.replace(/[^a-zA-Z0-9_-]/g,"-")}`;return(0,p.jsxs)("li",{className:g.item,children:[(0,p.jsxs)("button",{type:"button",className:`${g.row} ${e.highlight?g.highlight:""}`,style:{"--depth":n},onClick:()=>{d&&t(e=>!e)},disabled:!d,"aria-expanded":d?a:void 0,"aria-controls":d?c:void 0,children:[(0,p.jsx)("span",{className:g.expander,"aria-hidden":"true",children:i?a?(0,p.jsx)(m.A,{size:14,strokeWidth:2.5}):(0,p.jsx)(u,{size:14,strokeWidth:2.5}):null}),(0,p.jsx)(x,{item:e,isFolder:i}),(0,p.jsxs)("span",{className:g.name,children:[e.name,i?"/":""]})]}),a&&o?(0,p.jsx)("ul",{id:c,className:g.group,children:e.children?.map(s=>(0,p.jsx)(j,{item:s,depth:n+1,path:`${r}-${s.name}`},`${e.name}-${s.name}`))}):null]})}function y({items:e}){return(0,p.jsx)("div",{className:g.tree,role:"tree","aria-label":"Example project structure",children:(0,p.jsx)("ul",{className:g.group,children:e.map(e=>(0,p.jsx)(j,{item:e,path:e.name},e.name))})})}},48193:(e,n,r)=>{r.d(n,{R:()=>t,x:()=>o});var s=r(30758);const i={},a=s.createContext(i);function t(e){const n=s.useContext(a);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:t(e.components),s.createElement(a.Provider,{value:n},e.children)}},52096:(e,n,r)=>{r.d(n,{A:()=>s});const s=(0,r(46493).A)("Braces",[["path",{d:"M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5c0 1.1.9 2 2 2h1",key:"ezmyqa"}],["path",{d:"M16 21h1a2 2 0 0 0 2-2v-5c0-1.1.9-2 2-2a2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1",key:"e1hn23"}]])},58540:(e,n,r)=>{r.d(n,{A:()=>s});const s=(0,r(46493).A)("Network",[["rect",{x:"16",y:"16",width:"6",height:"6",rx:"1",key:"4q2zg0"}],["rect",{x:"2",y:"16",width:"6",height:"6",rx:"1",key:"8cvhb9"}],["rect",{x:"9",y:"2",width:"6",height:"6",rx:"1",key:"1egb70"}],["path",{d:"M5 16v-3a1 1 0 0 1 1-1h12a1 1 0 0 1 1 1v3",key:"1jsf9p"}],["path",{d:"M12 12V8",key:"2874zd"}]])},78286:(e,n,r)=>{r.d(n,{A:()=>s});const s=(0,r(46493).A)("Users",[["path",{d:"M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2",key:"1yyitq"}],["circle",{cx:"9",cy:"7",r:"4",key:"nufk8"}],["path",{d:"M22 21v-2a4 4 0 0 0-3-3.87",key:"kshegd"}],["path",{d:"M16 3.13a4 4 0 0 1 0 7.75",key:"1da9ce"}]])}}]);