grommet-docs
grommet-docs copied to clipboard
Add a readiness label for properties or components
Expected Behavior
We need a way to indicate when a component or property is new and either not part of a released version of grommet, or is experimental and the interface has not solidified.
Actual Behavior
When a grommet component is documented, the documentation appears immediately and there's no way to determine if it it's in a released version of grommet. When a property is added to documentation, there's no indication that it's stable and will not change without a breaking change.
Design suggestions
Use the Grommet Tag at the component level to designate that a component is one of:
- experimental - a component or property is in the stable branch and possibly in a released version of grommet, but its interface and capability is not yet finalized. Changes to visual, behavior, and API are likely for experimental components or properties. A Change to experimental components and properties will not be considered a breaking change.
- pre-release - a component or property is ready for use in the stable branch of grommet, but is not yet available in a released version of grommet. Minor changes to the component or property are possible without being considered a breaking change.
- released - a component or property is ready for use and is available in a released version of grommet. Changes to the component will be made in a backwards compatible manner or will be made as part of a major version update. In the case of a breaking change, the change will be documented in the release notes.
Considerations
- After writing the above, I'm wondering that maybe we don't need the *released tag as it's implied if neither of the other two are present.
- It would be nice to have a small Tag to use for experimental or pre-release properties and the "normal size" tag at the component level.
- It would be nice to be able to set the color on tags so we can use different colors for the tags, like the red explicit tag in Apple Music for experimental tags.
- We will need a docs page with describing the meaning of the tags similar to the above.
Design investigation underway. Need a dev for help in implementation.
Adding to v2.