Semantic Versioning

<p>Simplified <a rel="noreferrer noopener nofollow ugc" href="https://semver.org/" target="_blank">Semantic Versioning</a> for your Figma Nodes without external dependencies and consumable via API.</p><h2><br></h2><p>Features:</p><ul><li>Guided Semantic Versioning for your Nodes.</li><li>Issue Figma Document-Versions alongside the node versions.</li><li>History (and undo) the versioning.</li><li>Commit Messages</li><li>Consumable version information via Figma REST-API</li></ul><p><br></p><p>This plugin intents to help you keeping track of changes to your design by simply attaching a version number to your nodes.</p><p><br></p><p>The version number might be used to indicate the expected backend work triggered by the current design changes.</p><p><br></p><p>And it also allows you to reference the version in other tools and assets like issue trackers and documentation.</p><p><br></p><p>This plugin has&nbsp;<strong>no</strong>&nbsp;external dependencies, the version information is saved in the current document.</p><p><br></p><p><em>Be aware the meaning of the word "backend" depends highly on your project setup. In a progressive web app the "backend" is usually a front-end implementation whereas backend in a classical server-based webpage will be the actual server-side webapp implementation.</em></p><h2><br></h2><h2>How to use this Plugin?</h2><p>Select one or more nodes and run the plugin. If you're not selecting any nodes the plugin will show all <strong>versioned</strong> nodes on your current page.</p><h2><br></h2><h2>How to use the Version Workflow?</h2><p>The version number consist of three to four numerical parts:</p><p><br></p><pre spellcheck="false" class="ql-syntax">MAJOR.MINOR.PATCH(-rfc.RFC) </pre><p><br></p><p>The Rfc-part in brackets is optional and depends on the "requests for comments" setting.</p><p>The numbers are supposed to increment only.</p><p><br></p><p><strong>MAJOR</strong></p><p>The MAJOR-release number increase marks a&nbsp;backward-incompatible&nbsp;change of your design.</p><p><br></p><p>Imagine you changed a frame containing a form by removing an input. As you might assume this will break the current implementation of the app using this design because the app actually works with that input and might expect a value attached to it.</p><p><br></p><p>Propagating this change will likely break the backend-implementation. You communicate this by increasing the major release number by one actually saying this is a backward-incompatible change. And you expect it to break the current implementation.</p><p><br></p><p><strong>MINOR</strong></p><p>The MINOR-release number increase marks a&nbsp;backward-compatible&nbsp;change of your design, usually by adding a feature.</p><p><br></p><p>Imagine you extended the functionality of a frame by changing the design to display an additional input element. While this will require backend work to make the input actually work, rolling out the design won't break the application. So that is a backward compatible change of the current design.</p><p><br></p><p>Increasing the MINOR release version communicates you added a change which might require backend work but won't break the current backend implementation.</p><p><br></p><p><strong>PATCH</strong></p><p>The PATCH-release number increase marks a simple fix of your design which does not require any backend work.</p><p><br></p><p>Let's say you adjust some colors or got a ticket telling you a responsiveness feature isn't working as expected. By fixing this you correct the intentional implementation of the current design.</p><p><br></p><p>By using the PATCH version number you communicate there is no change in the backend-interface of your design and it won't require any backend changes.</p><p><br></p><p><strong>RFC</strong></p><p>Depending on your surrounding development process you might not be able to decide on your own when a design is ready to release. In this case you may enable the "request for comments"-based workflow.</p><p><br></p><p>The Rfc-workflow adds a&nbsp;<code>-rfc.1</code>-label to the version reflecting the current iteration in your approval process.</p><p><br></p><p>Let's say you make a first draft of a form, since it's a minor change, you choose to add a minor-change and because you have the rfc-workflow enabled you're only minor release option (given your current version is&nbsp;<code>1.0.0</code>) is&nbsp;<code>1.1.0-rfc.1</code>. This communicates you drafted a first version of the intended minor change.</p><p>Your team then discusses your draft and gives you some feedback which requires changes. After these changes you increase the Rfc number resulting in&nbsp;<code>1.1.0-rfc.2</code>. After another discussion with your team all are fine with the changes and you release the design to&nbsp;<code>1.1.0</code>.</p><h2><br></h2><h2>How to use the Settings?</h2><p>The settings are saved per page. That said you will have to adjust the settings once per page.</p><p><br></p><p><strong>Use "request for comments"</strong></p><p>Checking this option enables a "pre-release" path for your versioning which adds the&nbsp;<code>-rfc.&lt;&lt;number&gt;&gt;</code>&nbsp;counter to the version.</p><p><br></p><p>Using this feature allows you to mark your changes as a "proposal" depending on the workflow your design work is embedded in.</p><p><br></p><p>Unchecking this option changes only the available options for you next version change and does&nbsp;not&nbsp;automatically change any saved versions in the document.</p><p><br></p><p><strong>Use commit messages</strong></p><p>Checking this option shows a text field to take a optional commit message. The draft of a commit message is internally saved in the node. The commit message is saved in a small history (currently up to 5 elements) being consumabe via the Figma API.</p><p><br></p><p><strong>Use version appendix at Node names</strong></p><p>Checking this option enables&nbsp;<code>@</code>-prefixed version appendices for node names. When you save a version on a node, an&nbsp;<code>@</code>-symbol will be added to node name (if it not already exists) and the saved version is appended to the name.</p><p><br></p><p>This feature also adds two more version options "From Appendix" and "To Appendix" to the user interface (if the version appendix and the internal version of that node differ) allowing you to f.e. manually set or remove the version. Please keep in mind that&nbsp;<code>0.x</code>&nbsp;versions are not supported by this plugin.</p><p><br></p><p>Unchecking this option does currently not remove any version appendices. If you want to remove any version appendices from your nodes you will have to do this manually at the moment.</p><h2><br></h2><p><strong>Issue the save of a new Figma file version..</strong></p><p>With this option enabled, the plugin will submit any version change (may it be Initial, Major, Minor, Patch, Rfc or Release) to the Figma version history (<a rel="noreferrer noopener nofollow ugc" href="https://help.figma.com/hc/en-us/articles/360038006754-View-a-file-s-version-history" target="_blank">https://help.figma.com/hc/en-us/articles/360038006754-View-a-file-s-version-history</a>).</p><p><br></p><p>The version title will be "Nodename@Version" and the description will be the commit message if enabled and provided.</p><p><br></p><p><br></p><h2>API</h2><p>Purpose of this interface is to provide external access to the stored version number and the retained commit history per node.</p><p><br></p><p>Please consult the repository for more information: <a rel="noreferrer noopener nofollow ugc" href="https://github.com/florianb/figma-semantic-versioning#api" target="_blank">https://github.com/florianb/figma-semantic-versioning#api</a></p>