docs(pie-monorepo): DSW-000 update readme with component status info (#…

…2116) * docs(pie-monorepo): DSW-000 update readme information about component status * docs(pie-monorepo): DSW-000 revert formatting changes * docs(pie-monorepo): DSW-000 address review comments * Update packages/components/README.md Co-authored-by: Xander Marjoram <[email protected]> * Update packages/components/README.md Co-authored-by: Xander Marjoram <[email protected]> * docs(pie-monorepo): DSW-000 remove whitespaces on headings --------- Co-authored-by: Xander Marjoram <[email protected]>
justeattakeaway · Dec 17, 2024 · f58894c · f58894c
1 parent 0cc6853
commit f58894c
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 74 deletions.
diff --git a/.changeset/short-brooms-share.md b/.changeset/short-brooms-share.md
@@ -0,0 +1,7 @@
+---
+"pie-storybook": patch
+"pie-docs": patch
+"pie-monorepo": patch
+---
+
+[Changed] - Updates Readme information about component status
diff --git a/apps/pie-docs/component-statuses.json b/apps/pie-docs/component-statuses.json
diff --git a/apps/pie-storybook/component-statuses.json b/apps/pie-storybook/component-statuses.json
diff --git a/component-statuses.json b/component-statuses.json
diff --git a/packages/components/README.md b/packages/components/README.md
@@ -57,7 +57,7 @@ const component = await mount(
         {
             props: {
               variant: 'secondary',
-            }
+            },
             slots: {
                 default: 'Click me!',
             },
@@ -112,4 +112,30 @@ As with the browser tests, it is vital that the component to test is mounted and
 When we build a component, we run a plugin for Rollup named `rollup-plugin-visualizer`. This generates a file for each component named `stats.html` in the root of the component package. This file can be viewed in the browser to visualise the bundled Javascript and better understand what contributes to the size of the final build output.
 
 ## Component Status changes
-The `package.json` file of each component is the source of truth for its status. Any change of status will be automatically reflected in Storybook and the Documentation site. There is no need to manually change the `component-statuses.json` file.
+The `package.json` file of each component is the source of truth for its status. Any change of status will be automatically reflected in Storybook and the Documentation site.
+
+Supported statuses are `alpha`, `beta` and `stable`.
+
+```json
+// package.json
+"pieMetadata": {
+  "componentStatus": "alpha"
+},
+```
+
+### Release Categorisation
+|                    | Prerelease/Alpha (v0.x.x)                                                                                                           | Beta (v0.x.x)                                                                                                            | Stable (v1.x.x)                                                                                                                                                                                                   |
+|--------------------|-------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **NPM Versioning** | Breaking changes should be expected. Component is still in active development and released as v0.x.x (indicating semver prerelease) | Breaking changes will be less likely, but could still occur due to component being integration tested with applications. | Component moves to v1.x.x NPM release. Breaking changes are communicated through version updates and any major feature changes will be tested as beta package releases.                                           | 
+| **Use in production applications is** | Not recommended. Component is still in active development and may have known issues. Is done so at application teams own risk.      | Is encouraged, but with appropriate level of caution for a beta package release. Thorough testing is recommended.        | Is encouraged and we don’t expect any obvious defects being found.  Component has already been tested in other applications and is therefore considered stable. As always, thorough testing is still recommended. | 
+
+### What to do as a contributor
+Versioning will happen automatically through our pipeline, and will use each commit description to determine the right version. Remember you can use `yarn cz` when committing any changes. You don't need to change versions manually in the `package.json`.
+
+#### When to change a component's status
+Use `alpha` during development of the first epic or MVP of the component.
+
+Once the MVP is done, the component will be released as `beta`. This is generally done by the PIE team.
+
+It will move to `stable` after it has been tested in at least 2 production environments. This is generally done by the PIE team.
+