diff --git a/.github/ISSUE_TEMPLATE/new_component.md b/.github/ISSUE_TEMPLATE/new_component.md index 1b7394ddf8..8157432874 100644 --- a/.github/ISSUE_TEMPLATE/new_component.md +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57c52c1103..42887c294b 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 2339e8054e..6c1c7a6a7b 100644 --- a/README.md +++ b/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: | \ No newline at end of file +| Wafer Map | | [Issue](https://github.com/ni/nimble/issues/924) | [:warning: - SB](https://nimble.ni.dev/storybook/?path=/docs/wafermap--docs) | :warning: | :warning: | diff --git a/change/@ni-nimble-components-8dcc0358-9f16-4e9a-a003-59ccc6ccee4d.json b/change/@ni-nimble-components-8dcc0358-9f16-4e9a-a003-59ccc6ccee4d.json new file mode 100644 index 0000000000..38105056f0 --- /dev/null +++ b/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" +} diff --git a/packages/nimble-components/CONTRIBUTING.md b/packages/nimble-components/CONTRIBUTING.md index 470c9ff4ab..cd5821bc2f 100644 --- a/packages/nimble-components/CONTRIBUTING.md +++ b/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