Update guidance on experimental components to call them "incubating" (#…

…1249)

# Pull Request

## 🤨 Rationale

We had a team discussion about encouraging more Nimble contributions for
things like app-specific table columns. This update captures policies
for those components in CONTRIBUTING.md

## 👩‍💻 Implementation

Update the "Experimental" section of CONTRIBUTING.md to call these
components "Incubating" and provide more detailed guidance.

Small updates to related documentation about component status and
semver.

## 🧪 Testing
N/A

## ✅ Checklist

<!--- Review the list and put an x in the boxes that apply or ~~strike
through~~ around items that don't (along with an explanation). -->

- [x] I have updated the project documentation to reflect my changes or
determined no changes are needed.

.github/ISSUE_TEMPLATE/new_component.md

@@ -34,4 +34,4 @@ IBUTING](https://github.com/ni/nimble/blob/main/packages/nimble-components/CONTR
 - [ ] nimble-{name} Blazor wrapper
 - [ ] Add to Angular example app
 - [ ] Add to Blazor example app
-- [ ] Update Component Status table in README
+- [ ] Update Component Status table in README and incubating status

CONTRIBUTING.md

@@ -72,7 +72,7 @@ This repository uses [beachball](https://microsoft.github.io/beachball/) to auto
 3. A pipeline will run for each newly created git tag and invoke the `npm run publish` command for the associated package.
 
 When generating a change file, follow these guidelines:
-1. Follow [semantic versioning](https://semver.org) when choosing the change type. Components that are [marked as in-development](/packages/nimble-components/CONTRIBUTING.md/#Marking-a-component-as-in-development) may use `patch` version bumps even for breaking changes.
+1. Follow [semantic versioning](https://semver.org) when choosing the change type. Components that are [marked as incubating](/packages/nimble-components/CONTRIBUTING.md/#Marking-a-component-as-incubating) may use `patch` version bumps even for breaking changes.
 2. Write a brief but useful description with Nimble clients in mind. If making a major (breaking) change, explain what clients need to do to adopt it. The description can be plain text or [markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax), with newlines specified via `\n` if needed.
 3. If you prefer not to expose your email address to the world, [configure GitHub to "Keep my email address private"](https://github.com/settings/emails) before generating the change file.
 

README.md

@@ -64,6 +64,11 @@ NOTE: To update the component status:
     2. Create a PR to update this README with the entire contents of the generated 'M' column in the spreadsheet
 -->
 
+Legend:
+ - :white_check_mark: means the component is ready for general use
+ - :warning: is used for components that are "incubating". These are not ready for general use and may make breaking changes without a "major" semantic version bump.
+ - :o: means the component doesn't exist yet. Please submit requests by commenting on the linked issue.
+
 | Components             | Design | Issue | Web Components     | Angular Integration | Blazor Integration |
 |------------------------|--------|--------|--------------------|---------------------|--------------------|
 | Accordion | |  [Issue](https://github.com/ni/nimble/issues/533) | :o: | :o: | :o: |
@@ -99,7 +104,7 @@ NOTE: To update the component status:
 | Spinner | [XD](https://xd.adobe.com/view/6fc414f4-1660-4bff-4552-3e62baaa9e1e-19f5/screen/ced36959-68d6-440f-a0cc-031bc29d7e98/) |  [Issue](https://github.com/ni/nimble/issues/346) | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/spinner--docs) | :white_check_mark: | :white_check_mark: |
 | Split Icon Button | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/d022d8af-22f4-4bf2-981c-1dc0c61afece) |  [Issue](https://github.com/ni/nimble/issues/298) | :o: | :o: | :o: |
 | Switch | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/3698340b-8162-4e5d-bf7a-20194612b3a7/) |  [Issue](https://github.com/ni/nimble/issues/387) | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/switch--docs) | :white_check_mark: | :white_check_mark: |
-| Table | [XD](https://xd.adobe.com/view/5b476816-dad1-4671-b20a-efe796631c72-0e14/screen/d389dc1e-da4f-4a63-957b-f8b3cc9591b4/specs/) |  [Issue](https://github.com/orgs/ni/projects/11) | [:warning: - SB](https://nimble.ni.dev/storybook/?path=/docs/table--docs) | :warning: | :o: |
+| Table | [XD](https://xd.adobe.com/view/5b476816-dad1-4671-b20a-efe796631c72-0e14/screen/d389dc1e-da4f-4a63-957b-f8b3cc9591b4/specs/) |  [Issue](https://github.com/orgs/ni/projects/11) | [:warning: - SB](https://nimble.ni.dev/storybook/?path=/docs/table--docs) | :warning: | :warning: |
 | Tabs | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/b2aa2c0c-03b7-4571-8e0d-de88baf0814b) | | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/tabs--docs) | :white_check_mark: | :white_check_mark: |
 | Text and Icon Button | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/a378bcdb-5c4b-4298-b3b1-28d8b1a37af2) | | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/button--docs) | :white_check_mark: | :white_check_mark: |
 | Text Button | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/42001df1-2969-438e-b353-4327d7a15102) | | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/button--docs) | :white_check_mark: | :white_check_mark: |
@@ -109,4 +114,4 @@ NOTE: To update the component status:
 | Toolbar | |  [Issue](https://github.com/ni/nimble/issues/411) | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/toolbar--docs) | :white_check_mark: | :white_check_mark: |
 | Tooltip | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/044414d7-1714-40f2-9679-2ce2c8202d1c/) |  [Issue](https://github.com/ni/nimble/issues/309) | [:warning: - SB](https://nimble.ni.dev/storybook/?path=/docs/tooltip--docs) | :warning: | :warning: |
 | Tree View | [XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/ec5a855a-4174-46ad-947c-3931bbf3e32d/) | | [:white_check_mark: - SB](https://nimble.ni.dev/storybook/?path=/docs/tree-view--docs) | :white_check_mark: | :white_check_mark: |
-| Wafer Map | |  [Issue](https://github.com/ni/nimble/issues/924) | [:warning: - SB](https://nimble.ni.dev/storybook/?path=/docs/wafermap--docs) | :warning: | :warning: |
+| Wafer Map | |  [Issue](https://github.com/ni/nimble/issues/924) | [:warning: - SB](https://nimble.ni.dev/storybook/?path=/docs/wafermap--docs) | :warning: | :warning: |

change/@ni-nimble-components-8dcc0358-9f16-4e9a-a003-59ccc6ccee4d.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Documentation updates for policies around incubating components",
+  "packageName": "@ni/nimble-components",
+  "email": "jattasNI@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/nimble-components/CONTRIBUTING.md

@@ -77,15 +77,33 @@ Before building a new component, 3 specification documents need to be created:
 
 ## Develop new components
 
-### Marking a component as in development
+### Marking a component as incubating
 
-If a component will require multiple pull requests before having a complete and stable API, it should be marked as "in-development" to indicate to clients that they shouldn't start using it yet. To do this:
+If a component is not ready for general use, it should be marked as "incubating" to indicate that status to clients. A component could be in this state if any of the following are true:
+
+-   It is still in development.
+-   It is currently experimental or application-specific and hasn't yet been generalized for broader use.
+-   It is missing important features like interaction design, visual design, accessibility, or framework integration.
+
+Incubating contributions may compromise on the above capabilities but they still must abide by other repository requirements. For example:
+
+-   Start development with a spec describing the high level plan and what's in or out of scope
+-   Coding conventions (element naming, linting, code quality)
+-   Unit and Chromatic test coverage
+-   Storybook documentation
+
+To mark a component as incubating:
 
 1. In the component status table, set its status to ⚠️
-2. In the component Storybook documentation, add a red text banner to the page indicating that the component should not be used
-3. Consider placing the component implementation in a sub-folder named `experimental` so that it will be obvious when importing it that it is incomplete
+2. In the component Storybook documentation:
+    - add a red text banner to the page indicating that the component is not ready for general use
+    - start the Storybook name with "Incubating/" so that it appears in a separate section of the documentation page
+3. Add CODEOWNERS from both the contributing team and the Nimble team.
+
+To move a component out of incubating status:
 
-Be sure to remove these warnings when the component is complete!
+1. Have a conversation with the Nimble team to decide if it is sufficiently complete.
+2. Update the markings described above to indicate that it is now ready for general use!
 
 ### Folder structure