Merged in rfc-component-evolution (pull request #245)

docs: document the beta/supported/deprecated cycle for breaking component changes

Approved-by: Daragh King

COMPONENT_EVOLUTION.md

@@ -0,0 +1,65 @@
+# Component Evolution
+
+This document describes a mechanism for handling breaking changes to components (API or design
+changes) in a way that supports gradual adoption by development teams. We also want to limit how
+often teams have to deal with breaking changes to a fairly regular and infrequent cadence.
+
+## Beta, Supported, Legacy Cycle
+
+The mechanism for handling these transitions will be for breaking changes in components to go through
+a series of states:
+
+- Beta: Beta components are available in the library for early adopters, but subject to breaking
+  change without a major version bump, most likely based on feedback from the teams using it.
+
+- Supported: This is the normal component version, the default approach teams should use. No breaking
+  changes outside of a major package version bump. Most components should be in this state most of the
+  time.
+
+- Legacy: Legacy components let teams defer handling significant breaking API changes in a
+  component for a reasonable amount of time after a major version change. There will be some work
+  required to stay on a legacy version, but it should be simple and quick.
+
+This cycle is implemented on a per-component basis by adding a `-beta` or `-legacy` suffix to
+the component element names for the respective states.
+
+## Migrations
+
+On a major release all component state changes will be documented and presented in an easy to follow migration guide.
+
+### beta → supported
+
+If the application is using the latest beta version of the component there will be no need for code
+changes other than removing the `-beta` suffix. If the beta version is out of date there may be a
+need for some development work as the components api may have changed. A component will not move to
+the supported state unless it is well documented so this migration should be straight-forward.
+
+### supported → legacy
+
+There will be no need for code changes other than adding the `-legacy` suffix. At this stage the
+development team should start planning to move to the supported version before the next major release.
+
+### legacy → supported
+
+When a component version is deprecating a migration guide will be created to help development teams
+move to the newly supported component.
+
+## Rotation Schedule
+
+Components will rotate through the beta/supported/legacy cycle on roughly a quarterly basis.
+Once a quarter, any beta components implementations that are sufficiently stable will become
+supported components. The previously supported version of that component will become legacy,
+and any previously legacy components will be removed from the library entirely.
+
+For a team that does not want to migrate right away to the new APIs, staying on the legacy
+version of a component should just involve a straighforward find-and-replace to add `-legacy` to
+the components. Those teams can then move to the new API anytime in the next quarter before the
+legacy components are removed.
+
+## FAQ
+
+Q: Does this mean I'll have to upgrade a bunch of components every three months?
+A: No, the overall goal is always to have as few breaking changes as possible. We expect to
+eventually reach a point where we go entire quarters without any breaking changes at all.
+
+More to be added when people ask questions...

README.md

@@ -11,16 +11,20 @@ Distribution Groups"
 
 You may also want to join the chat room for the Genesys Cloud [Common UI Development Group](https://apps.mypurecloud.com/directory/#/group/3fd509fa-c20b-4cfe-ab01-f81588d2a510)
 
+At any given time there are three types of components present in the library:
+
+- **stable**: Most components fall into this category, and there will be no breaking api changes outside of a major release.
+- **beta**: New components where the API design is still being explored. Breaking changes _may_ happen without a major version change.
+- **legacy**: Old components that have been replaced by a new component, or a newer version of the component witn an incompatible API. These will be removed in the next major release.
+
+For more details on the component evolutin process see the full [documentation on the topic](./COMPONENT_EVOLUTION.md)
+
 ## Demo/Documentation
 
 [Lives here](https://apps.inindca.com/common-ui-docs/#/genesys-webcomponents/latest)
 
 ## Installing the library
 
-Currently the main line of development is done in the 1.0.0-alpha branch/release. This is because we are working on making
-changes to the APIs of some components to bring them up to our [API design standards](COMPONENT_DESIGN.md). The elements
-that are currently likely to change are documented by the `likely-breaking-changes` label [in JIRA](<https://inindca.atlassian.net/issues/?jql=project%20%3D%20%22COMUI%22%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20in%20(likely-breaking-changes)%20ORDER%20BY%20priority%20DESC>).
-
 ### Prerequisites
 
 Published artifacts are stored in our private artifactory/jfrog registry, so you will need to update your

docs/src/component-pages/gux-switch.html

@@ -5,24 +5,25 @@
   <body>
     <script src="${CDN_URL}index.js"></script>
     <script>
-      webcomponentsDocsMain(`
+      webcomponentsDocsMain(
+        `
 <div>Small</div>
-<gux-switch id="small"
+<gux-switch-beta id="small"
     layout="small"
     selected-value="Day"
-></gux-switch>
+></gux-switch-beta>
 
 <div>Medium</div>
-<gux-switch id="medium"
+<gux-switch-beta id="medium"
     layout="medium"
     selected-value="Minute"
-></gux-switch>
+></gux-switch-beta>
 
 <div>Large</div>
-<gux-switch id="large"
+<gux-switch-beta id="large"
     layout="large"
     selected-value="Month"
-></gux-switch>
+></gux-switch-beta>
 <!--
 [ document.getElementById('small')
 , document.getElementById('medium')
@@ -47,30 +48,39 @@
     }];
 });
 -->
-`, function () {
-    [ document.getElementById('small')
-    , document.getElementById('medium')
-    , document.getElementById('large')
-    ].forEach(function (s) {
-        s.items = [{
-            displayName: 'Month',
-            value: 'Month'
-        }, {
-            displayName: 'Week',
-            value: 'Week'
-        }, {
-            displayName: 'Day',
-            value: 'Day'
-        }, {
-            displayName: 'Hour',
-            isDisabled: true,
-            value: 'Hour'
-        }, {
-            displayName: 'Minute',
-            value: 'Minute'
-        }];
-    });
-});
+`,
+        function () {
+          [
+            document.getElementById('small'),
+            document.getElementById('medium'),
+            document.getElementById('large')
+          ].forEach(function (s) {
+            s.items = [
+              {
+                displayName: 'Month',
+                value: 'Month'
+              },
+              {
+                displayName: 'Week',
+                value: 'Week'
+              },
+              {
+                displayName: 'Day',
+                value: 'Day'
+              },
+              {
+                displayName: 'Hour',
+                isDisabled: true,
+                value: 'Hour'
+              },
+              {
+                displayName: 'Minute',
+                value: 'Minute'
+              }
+            ];
+          });
+        }
+      );
     </script>
   </body>
 </html>

scripts/build-i18n.js

@@ -12,7 +12,7 @@ const path = require('path');
 
 const filePatternRegex = /[\/\\]([^\/\\]+)\/i18n\/([^.]+)\.json$/;
 const translationsFolder = path.join(__dirname, '../build/i18n');
-const localesFile = path.join(__dirname, '../src/components/i18n/locales.json');
+const localesFile = path.join(__dirname, '../src/i18n/locales.json');
 
 glob('src/components/**/i18n/*.json', (err, files) => {
   if (err) {

src/components/form/gux-form-field/components/gux-error-message-beta/readme.md → src/components/beta/form/gux-form-field/components/gux-error-message-beta/readme.md

@@ -16,7 +16,7 @@
 
 ### Depends on
 
-- [gux-icon](../../../../gux-icon)
+- [gux-icon](../../../../../stable/gux-icon)
 
 ### Graph
 ```mermaid

src/components/form/gux-form-field/components/gux-input-color-beta/readme.md → src/components/beta/form/gux-form-field/components/gux-input-color-beta/readme.md

@@ -20,7 +20,7 @@
 
 ### Depends on
 
-- [gux-icon](../../../../gux-icon)
+- [gux-icon](../../../../../stable/gux-icon)
 - [gux-input-color-select-beta](../gux-input-color/components/gux-color-select-beta)
 
 ### Graph

src/components/gux-command-palette/gux-command-palette.less → src/components/beta/gux-command-palette/gux-command-palette.less

@@ -6,7 +6,7 @@
 @palette-shadow: rgba(34, 37, 41, 0.24);
 
 // Style
-gux-command-palette .gux-command-palette {
+gux-command-palette-beta .gux-command-palette {
   border-color: 1px solid @palette-border-color;
   box-shadow: 0px 0 2px 0px @palette-shadow;
   position: absolute;
@@ -139,12 +139,12 @@ gux-command-palette .gux-command-palette {
 }
 
 .gux-dark-theme {
-  gux-command-palette {
+  gux-command-palette-beta {
     .gux-command-palette-dark-theme();
   }
 }
 
-gux-command-palette.gux-dark-theme {
+gux-command-palette-beta.gux-dark-theme {
   .gux-command-palette-dark-theme();
 }
 
@@ -174,16 +174,16 @@ gux-command-palette.gux-dark-theme {
 }
 
 .gux-light-theme {
-  gux-command-palette {
+  gux-command-palette-beta {
     .gux-command-palette-light-theme();
   }
 }
 
-gux-command-palette.gux-light-theme {
+gux-command-palette-beta.gux-light-theme {
   .gux-command-palette-light-theme();
 }
 
 // Default Theme
-gux-command-palette {
+gux-command-palette-beta {
   .gux-command-palette-light-theme();
 }

src/components/gux-command-palette/gux-command-palette.tsx → src/components/beta/gux-command-palette/gux-command-palette.tsx

@@ -1,7 +1,7 @@
 import { Component, Element, h, Method, State } from '@stencil/core';
-import { KeyCode } from '../../common-enums';
-import { matchesFuzzy } from '../../search';
-import { buildI18nForComponent } from '../i18n';
+import { KeyCode } from '../../../common-enums';
+import { matchesFuzzy } from '../../../search';
+import { buildI18nForComponent } from '../../../i18n';
 import paletteResources from './i18n/en.json';
 
 const filterLimit = 50;
@@ -38,7 +38,7 @@ function sortActions(
 
 @Component({
   styleUrl: 'gux-command-palette.less',
-  tag: 'gux-command-palette'
+  tag: 'gux-command-palette-beta'
 })
 export class GuxCommandPalette {
   @Element()
@@ -72,7 +72,7 @@ export class GuxCommandPalette {
         onKeyDown={e => this.onKeyDown(e)}
         aria-label={this.i18n('title')}
       >
-        <gux-search
+        <gux-search-beta
           sr-label={this.i18n('search')}
           onInput={(e: any) => {
             this.handleInput(e);
@@ -295,7 +295,7 @@ export class GuxCommandPalette {
   }
 
   private elementIsSearch(el: Element): boolean {
-    return el.closest('gux-search') !== null;
+    return el.closest('gux-search-beta') !== null;
   }
 
   private getParentGuxList(el: Element): HTMLGuxListElement {
@@ -309,7 +309,7 @@ export class GuxCommandPalette {
       return;
     }
 
-    const searchElement = el as HTMLGuxSearchElement;
+    const searchElement = el as HTMLGuxSearchBetaElement;
     if (searchElement && searchElement.setInputFocus) {
       searchElement.setInputFocus();
     }

src/components/gux-command-palette/readme.md → src/components/beta/gux-command-palette/readme.md

@@ -51,23 +51,23 @@ Type: `Promise<void>`
 
 ### Depends on
 
-- [gux-search](../gux-search)
-- [gux-list](../gux-list)
-- [gux-list-item](../gux-list/list-item)
-- [gux-text-highlight](../gux-text-highlight)
+- [gux-search-beta](../gux-search)
+- [gux-list](../../stable/gux-list)
+- [gux-list-item](../../stable/gux-list/list-item)
+- [gux-text-highlight](../../stable/gux-text-highlight)
 
 ### Graph
 ```mermaid
 graph TD;
-  gux-command-palette --> gux-search
-  gux-command-palette --> gux-list
-  gux-command-palette --> gux-list-item
-  gux-command-palette --> gux-text-highlight
-  gux-search --> gux-text-field
-  gux-search --> gux-icon
+  gux-command-palette-beta --> gux-search-beta
+  gux-command-palette-beta --> gux-list
+  gux-command-palette-beta --> gux-list-item
+  gux-command-palette-beta --> gux-text-highlight
+  gux-search-beta --> gux-text-field
+  gux-search-beta --> gux-icon
   gux-text-field --> gux-icon
   gux-list-item --> gux-text-highlight
-  style gux-command-palette fill:#f9f,stroke:#333,stroke-width:4px
+  style gux-command-palette-beta fill:#f9f,stroke:#333,stroke-width:4px
 ```
 
 ----------------------------------------------