Component lifecycle definition

[aweell]

The current problem

Recently released components labeled as ready

We are labeling as ready components released in version 4 that are still susceptible to changes (e.g. adding the title attribute to custom actions, integrating a tooltip or tooltip trigger from a specific element in the text-input component, text alignment...).

So..what a user should expect when a component is labeled as ready?

There's no definition across the design system documentation that explains what a user should expect when a component is labeled as ready.

Have all the components released in a version of the React or Angular CDKs the same level of maturity? I think they don't...

So...when a component is actually ready?

The idea of a component labeled as ready is a little different from how we're currently using it in my point of view:

Ready component:

• A component that is mature and there's no expected breaking changes in the API in (at least one release?)
• Has been tested in production
• Has usage guidelines, examples and props well documented
• It accessibility has been tested
• There's a UI-Kit component that can be used

*Note (When I say "my point of view" it's because I think I have a narrowed view of the definition of ready and it would be important to discuss this in detail)

Some of the components still need to go through a maturity process until they are labeled as stable, we're currently redefining the whole stack of components the DS has, and I think that we should provide better communication in terms of the status of our CDK components, utilities, guidelines, etc...

The proposal

The different statuses

Develop a component lifecycle where some checks define the status of the component

Label	Status	Description
	Alpha	The component is experimental, regular breaking changes expected, not ready for adoption
	Beta	The component is being tested in production, breaking changes expected, ready for adoption
	Stable	The component is mature and has been tested in multiple production environments, few breaking changes expected
	Deprecated	The component is planned to be removed from the design system

Other aspects that can define the status of the component are the presence of VRT, typed API, tests... I'm just opening the door to see which are the lines that a component/utility needs to cross to be defined as each status.

For this status description would be necessary to define:

• What are the artifacts expected in every status?
• How maturity is defined?
• What mean to be tested in production?
• Other relevant questions...

The overview / status page

Create a page where all this information is available for the design system users. It can be divided by technology (Angular / React)

Information that could be useful to display:

• Component / Utility name
• Component / Utility status
• Version of the UI-Kit where the component was released (Only apply to XD)
• Version of the CDK where the component was released
• Other aspects (e.g. responsive version? etc...)

Could be interesting to add what components are in progress or planned but we didn't started the implementation?

Some references

• Github primer - Component status
• Github primer - Component lifecycle
• Pharos - Component status
• Thumbprint - Components overview
• Salesforce lightning - Component overview

[GomezIvann]

Some topics I want to add to the discussion:

• In Beta state, "has been tested in production" I think we should specify a minimum amount of applications using the component actively. Also, I think is worth mentioning or clarifying that the breaking changes expected are due to issues or problems commented by people during the use of the component or things that we see in their apps not working properly.
• Is worth having a previous state to Alpha, where a component is approved, and may also be designed and documented, but not yet implemented? These states you defined depend much on the implementation rather than the documentation side, which I think should have an important role here.
• Maybe is also interesting to discuss a role called In progress for each version of a new component inside a release. Currently, we are uploading our progress of a component daily (or we try to), so next will always have unfinished versions of this new component, constantly being updated. We avoid this by not exporting the component and also not documenting it, maybe we can start adding its documentation from the beginning and marking it as 'In Progress' for users in the Next version of the CDK.
  In Progress: Actively being created, either by the maintainers or a contributor.
• Another state that I usually see and I think would be useful for us is 'Updated'. It should be used in components that were ready before and have gone through a restyling (like we did with Toggle Group).
• When a component is removed, should we completely remove it from documentation or just from the exports and have a new state called Removed or something like that.

I agree we should have a page explaining the possible states of a component with complete explanations for each of them. I also think that having an Overview page with each component status would add so much value.

[GomezIvann]

I agree we need to define very specific criteria for Beta state and we understand for "tested in production". We need to take into account many variables, a very important topic to discuss I think. Also, I think we need to establish a division between states, as you said. States for components 'In development' (maybe establishing a distinction between Design and actual Implementation?), states for 'Ready' components and states for the Deprecated ones.

[marcialfps]

I agree with both of you on the need to have a status page indicating the status of each component. I have the same question as @aweell , are 'in development' components included on this page? Maybe we can have such components on the page for experimental users. I think we need to define the purpose of this status page and if we need to add this type of components.

What mean to be tested in production?

I think this is a very important question. What is production in our case? Our sites? Internal platform applications?
And also, are these teams prepared to use components that are not mature?

When a component is removed, should we completely remove it from documentation or just from the exports and have a new state called Removed or something like that.

I am not sure about this state. If we have a status page for each release we don't need to include the removed components since they were mark as Deprecated in the previous version.

[aweell]

are 'in development' components included on this page? Maybe we can have such components on the page for experimental users.

For me, this page should display the components that are available in the CDKs (latest version released or the last merge to master) and their status, nothing related to design or development plans (those that are available in the open-source Github project).

When a component is removed, should we completely remove it from documentation or just from the exports and have a new state called Removed or something like that.

Regarding the removed state, I don't see any point in having it. The component was labeled as deprecated, so all documentation and references will be removed after the stipulated time ends. I propose to document in the halstack site how much time we're giving when we deprecate a component and an approximate date of its removal.

[GomezIvann]

I agree with not having a Removed state if we define somewhere else that Deprecated components will be removed after a certain period, perhaps after a complete release being marked as deprecated.

For me, this page should display the components that are available in the latest version released and their status, nothing related to design or development plans (those that are available in the open-source Github project).

I'm not so sure about this, I can see some value of, at least, showing some information about the new component. For example, when we develop a new component, from the beginning we know the API of the component and more or less its anatomy, and I think it would be interesting to show that kind of stuff to the user.

[aweell]

I'm not so sure about this, I can see some value of, at least, showing some information about the new component. For example, when we develop a new component, from the beginning we know the API of the component and more or less its anatomy, and I think it would be interesting to show that kind of stuff to the user.

We started doing that by opening our backlog in the GitHub projects, I feel that the cost of maintenance would exceed the value provided if we want to translate that information to the documentation site.

What I could see on that page maybe is a sub-section called: Coming soon? That links the planned components to the issues were define the design and API? I would be careful with that since it could be seen as a commitment. In addition, most of our discussions are offline, even though we're trying to document the process, only a small part of the design implications are documented.

The example of the radio-group:
#485

My suggestion here is to avoid increasing our documentation workload just for the sake of it. Stick to what's available in the CDKs and define the status of it (Either if we called it alpha or in progress or experimental).

[GomezIvann]

We can close this discussion, we have already defined a lifecycle for our components! https://developer.dxc.com/halstack/next/overview/component-lifecycle/